1 /** \file nifti1.h 2 \brief Official definition of the nifti1 header. Written by Bob Cox, SSCC, NIMH. 3 4 HISTORY: 5 6 29 Nov 2007 [rickr] 7 - added DT_RGBA32 and NIFTI_TYPE_RGBA32 8 - added NIFTI_INTENT codes: 9 TIME_SERIES, NODE_INDEX, RGB_VECTOR, RGBA_VECTOR, SHAPE 10 */ 11 12 #ifndef _NIFTI_HEADER_ 13 #define _NIFTI_HEADER_ 14 15 /***************************************************************************** 16 ** This file defines the "NIFTI-1" header format. ** 17 ** It is derived from 2 meetings at the NIH (31 Mar 2003 and ** 18 ** 02 Sep 2003) of the Data Format Working Group (DFWG), ** 19 ** chartered by the NIfTI (Neuroimaging Informatics Technology ** 20 ** Initiative) at the National Institutes of Health (NIH). ** 21 **--------------------------------------------------------------** 22 ** Neither the National Institutes of Health (NIH), the DFWG, ** 23 ** nor any of the members or employees of these institutions ** 24 ** imply any warranty of usefulness of this material for any ** 25 ** purpose, and do not assume any liability for damages, ** 26 ** incidental or otherwise, caused by any use of this document. ** 27 ** If these conditions are not acceptable, do not use this! ** 28 **--------------------------------------------------------------** 29 ** Author: Robert W Cox (NIMH, Bethesda) ** 30 ** Advisors: John Ashburner (FIL, London), ** 31 ** Stephen Smith (FMRIB, Oxford), ** 32 ** Mark Jenkinson (FMRIB, Oxford) ** 33 ******************************************************************************/ 34 35 /*---------------------------------------------------------------------------*/ 36 /* Note that the ANALYZE 7.5 file header (dbh.h) is 37 (c) Copyright 1986-1995 38 Biomedical Imaging Resource 39 Mayo Foundation 40 Incorporation of components of dbh.h are by permission of the 41 Mayo Foundation. 42 43 Changes from the ANALYZE 7.5 file header in this file are released to the 44 public domain, including the functional comments and any amusing asides. 45 -----------------------------------------------------------------------------*/ 46 47 /*---------------------------------------------------------------------------*/ 48 /*! INTRODUCTION TO NIFTI-1: 49 ------------------------ 50 The twin (and somewhat conflicting) goals of this modified ANALYZE 7.5 51 format are: 52 (a) To add information to the header that will be useful for functional 53 neuroimaging data analysis and display. These additions include: 54 - More basic data types. 55 - Two affine transformations to specify voxel coordinates. 56 - "Intent" codes and parameters to describe the meaning of the data. 57 - Affine scaling of the stored data values to their "true" values. 58 - Optional storage of the header and image data in one file (.nii). 59 (b) To maintain compatibility with non-NIFTI-aware ANALYZE 7.5 compatible 60 software (i.e., such a program should be able to do something useful 61 with a NIFTI-1 dataset -- at least, with one stored in a traditional 62 .img/.hdr file pair). 63 64 Most of the unused fields in the ANALYZE 7.5 header have been taken, 65 and some of the lesser-used fields have been co-opted for other purposes. 66 Notably, most of the data_history substructure has been co-opted for 67 other purposes, since the ANALYZE 7.5 format describes this substructure 68 as "not required". 69 70 NIFTI-1 FLAG (MAGIC STRINGS): 71 ---------------------------- 72 To flag such a struct as being conformant to the NIFTI-1 spec, the last 4 73 bytes of the header must be either the C String "ni1" or "n+1"; 74 in hexadecimal, the 4 bytes 75 6E 69 31 00 or 6E 2B 31 00 76 (in any future version of this format, the '1' will be upgraded to '2', 77 etc.). Normally, such a "magic number" or flag goes at the start of the 78 file, but trying to avoid clobbering widely-used ANALYZE 7.5 fields led to 79 putting this marker last. However, recall that "the last shall be first" 80 (Matthew 20:16). 81 82 If a NIFTI-aware program reads a header file that is NOT marked with a 83 NIFTI magic string, then it should treat the header as an ANALYZE 7.5 84 structure. 85 86 NIFTI-1 FILE STORAGE: 87 -------------------- 88 "ni1" means that the image data is stored in the ".img" file corresponding 89 to the header file (starting at file offset 0). 90 91 "n+1" means that the image data is stored in the same file as the header 92 information. We recommend that the combined header+data filename suffix 93 be ".nii". When the dataset is stored in one file, the first byte of image 94 data is stored at byte location (int)vox_offset in this combined file. 95 The minimum allowed value of vox_offset is 352; for compatibility with 96 some software, vox_offset should be an integral multiple of 16. 97 98 GRACE UNDER FIRE: 99 ---------------- 100 Most NIFTI-aware programs will only be able to handle a subset of the full 101 range of datasets possible with this format. All NIFTI-aware programs 102 should take care to check if an input dataset conforms to the program's 103 needs and expectations (e.g., check datatype, intent_code, etc.). If the 104 input dataset can't be handled by the program, the program should fail 105 gracefully (e.g., print a useful warning; not crash). 106 107 SAMPLE CODES: 108 ------------ 109 The associated files nifti1_io.h and nifti1_io.c provide a sample 110 implementation in C of a set of functions to read, write, and manipulate 111 NIFTI-1 files. The file nifti1_test.c is a sample program that uses 112 the nifti1_io.c functions. 113 -----------------------------------------------------------------------------*/ 114 115 /*---------------------------------------------------------------------------*/ 116 /* HEADER STRUCT DECLARATION: 117 ------------------------- 118 In the comments below for each field, only NIFTI-1 specific requirements 119 or changes from the ANALYZE 7.5 format are described. For convenience, 120 the 348 byte header is described as a single struct, rather than as the 121 ANALYZE 7.5 group of 3 substructs. 122 123 Further comments about the interpretation of various elements of this 124 header are after the data type definition itself. Fields that are 125 marked as ++UNUSED++ have no particular interpretation in this standard. 126 (Also see the UNUSED FIELDS comment section, far below.) 127 128 The presumption below is that the various C types have particular sizes: 129 sizeof(int) = sizeof(float) = 4 ; sizeof(short) = 2 130 -----------------------------------------------------------------------------*/ 131 132 /*=================*/ 133 #ifdef __cplusplus 134 extern "C" { 135 #endif 136 /*=================*/ 137 138 /*! \struct nifti_1_header 139 \brief Data structure defining the fields in the nifti1 header. 140 This binary header should be found at the beginning of a valid 141 NIFTI-1 header file. 142 */ 143 /*************************/ /************************/ 144 struct nifti_1_header { /* NIFTI-1 usage */ /* ANALYZE 7.5 field(s) */ 145 /*************************/ /************************/ 146 147 /*--- was header_key substruct ---*/ 148 int sizeof_hdr; /*!< MUST be 348 */ /* int sizeof_hdr; */ 149 char data_type[10]; /*!< ++UNUSED++ */ /* char data_type[10]; */ 150 char db_name[18]; /*!< ++UNUSED++ */ /* char db_name[18]; */ 151 int extents; /*!< ++UNUSED++ */ /* int extents; */ 152 short session_error; /*!< ++UNUSED++ */ /* short session_error; */ 153 char regular; /*!< ++UNUSED++ */ /* char regular; */ 154 char dim_info; /*!< MRI slice ordering. */ /* char hkey_un0; */ 155 156 /*--- was image_dimension substruct ---*/ 157 short dim[8]; /*!< Data array dimensions.*/ /* short dim[8]; */ 158 float intent_p1 ; /*!< 1st intent parameter. */ /* short unused8; */ 159 /* short unused9; */ 160 float intent_p2 ; /*!< 2nd intent parameter. */ /* short unused10; */ 161 /* short unused11; */ 162 float intent_p3 ; /*!< 3rd intent parameter. */ /* short unused12; */ 163 /* short unused13; */ 164 short intent_code ; /*!< NIFTI_INTENT_* code. */ /* short unused14; */ 165 short datatype; /*!< Defines data type! */ /* short datatype; */ 166 short bitpix; /*!< Number bits/voxel. */ /* short bitpix; */ 167 short slice_start; /*!< First slice index. */ /* short dim_un0; */ 168 float pixdim[8]; /*!< Grid spacings. */ /* float pixdim[8]; */ 169 float vox_offset; /*!< Offset into .nii file */ /* float vox_offset; */ 170 float scl_slope ; /*!< Data scaling: slope. */ /* float funused1; */ 171 float scl_inter ; /*!< Data scaling: offset. */ /* float funused2; */ 172 short slice_end; /*!< Last slice index. */ /* float funused3; */ 173 char slice_code ; /*!< Slice timing order. */ 174 char xyzt_units ; /*!< Units of pixdim[1..4] */ 175 float cal_max; /*!< Max display intensity */ /* float cal_max; */ 176 float cal_min; /*!< Min display intensity */ /* float cal_min; */ 177 float slice_duration;/*!< Time for 1 slice. */ /* float compressed; */ 178 float toffset; /*!< Time axis shift. */ /* float verified; */ 179 int glmax; /*!< ++UNUSED++ */ /* int glmax; */ 180 int glmin; /*!< ++UNUSED++ */ /* int glmin; */ 181 182 /*--- was data_history substruct ---*/ 183 char descrip[80]; /*!< any text you like. */ /* char descrip[80]; */ 184 char aux_file[24]; /*!< auxiliary filename. */ /* char aux_file[24]; */ 185 186 short qform_code ; /*!< NIFTI_XFORM_* code. */ /*-- all ANALYZE 7.5 ---*/ 187 short sform_code ; /*!< NIFTI_XFORM_* code. */ /* fields below here */ 188 /* are replaced */ 189 float quatern_b ; /*!< Quaternion b param. */ 190 float quatern_c ; /*!< Quaternion c param. */ 191 float quatern_d ; /*!< Quaternion d param. */ 192 float qoffset_x ; /*!< Quaternion x shift. */ 193 float qoffset_y ; /*!< Quaternion y shift. */ 194 float qoffset_z ; /*!< Quaternion z shift. */ 195 196 float srow_x[4] ; /*!< 1st row affine transform. */ 197 float srow_y[4] ; /*!< 2nd row affine transform. */ 198 float srow_z[4] ; /*!< 3rd row affine transform. */ 199 200 char intent_name[16];/*!< 'name' or meaning of data. */ 201 202 char magic[4] ; /*!< MUST be "ni1\0" or "n+1\0". */ 203 204 } ; /**** 348 bytes total ****/ 205 206 typedef struct nifti_1_header nifti_1_header ; 207 208 /*---------------------------------------------------------------------------*/ 209 /* HEADER EXTENSIONS: 210 ----------------- 211 After the end of the 348 byte header (e.g., after the magic field), 212 the next 4 bytes are a char array field named "extension". By default, 213 all 4 bytes of this array should be set to zero. In a .nii file, these 214 4 bytes will always be present, since the earliest start point for 215 the image data is byte #352. In a separate .hdr file, these bytes may 216 or may not be present. If not present (i.e., if the length of the .hdr 217 file is 348 bytes), then a NIfTI-1 compliant program should use the 218 default value of extension={0,0,0,0}. The first byte (extension[0]) 219 is the only value of this array that is specified at present. The other 220 3 bytes are reserved for future use. 221 222 If extension[0] is nonzero, it indicates that extended header information 223 is present in the bytes following the extension array. In a .nii file, 224 this extended header data is before the image data (and vox_offset 225 must be set correctly to allow for this). In a .hdr file, this extended 226 data follows extension and proceeds (potentially) to the end of the file. 227 228 The format of extended header data is weakly specified. Each extension 229 must be an integer multiple of 16 bytes long. The first 8 bytes of each 230 extension comprise 2 integers: 231 int esize , ecode ; 232 These values may need to be byte-swapped, as indicated by dim[0] for 233 the rest of the header. 234 * esize is the number of bytes that form the extended header data 235 + esize must be a positive integral multiple of 16 236 + this length includes the 8 bytes of esize and ecode themselves 237 * ecode is a non-negative integer that indicates the format of the 238 extended header data that follows 239 + different ecode values are assigned to different developer groups 240 + at present, the "registered" values for code are 241 = 0 = unknown private format (not recommended!) 242 = 2 = DICOM format (i.e., attribute tags and values) 243 = 4 = AFNI group (i.e., ASCII XML-ish elements) 244 In the interests of interoperability (a primary rationale for NIfTI), 245 groups developing software that uses this extension mechanism are 246 encouraged to document and publicize the format of their extensions. 247 To this end, the NIfTI DFWG will assign even numbered codes upon request 248 to groups submitting at least rudimentary documentation for the format 249 of their extension; at present, the contact is mailto:rwcox@nih.gov. 250 The assigned codes and documentation will be posted on the NIfTI 251 website. All odd values of ecode (and 0) will remain unassigned; 252 at least, until the even ones are used up, when we get to 2,147,483,646. 253 254 Note that the other contents of the extended header data section are 255 totally unspecified by the NIfTI-1 standard. In particular, if binary 256 data is stored in such a section, its byte order is not necessarily 257 the same as that given by examining dim[0]; it is incumbent on the 258 programs dealing with such data to determine the byte order of binary 259 extended header data. 260 261 Multiple extended header sections are allowed, each starting with an 262 esize,ecode value pair. The first esize value, as described above, 263 is at bytes #352-355 in the .hdr or .nii file (files start at byte #0). 264 If this value is positive, then the second (esize2) will be found 265 starting at byte #352+esize1 , the third (esize3) at byte #352+esize1+esize2, 266 et cetera. Of course, in a .nii file, the value of vox_offset must 267 be compatible with these extensions. If a malformed file indicates 268 that an extended header data section would run past vox_offset, then 269 the entire extended header section should be ignored. In a .hdr file, 270 if an extended header data section would run past the end-of-file, 271 that extended header data should also be ignored. 272 273 With the above scheme, a program can successively examine the esize 274 and ecode values, and skip over each extended header section if the 275 program doesn't know how to interpret the data within. Of course, any 276 program can simply ignore all extended header sections simply by jumping 277 straight to the image data using vox_offset. 278 -----------------------------------------------------------------------------*/ 279 280 /*! \struct nifti1_extender 281 \brief This structure represents a 4-byte string that should follow the 282 binary nifti_1_header data in a NIFTI-1 header file. If the char 283 values are {1,0,0,0}, the file is expected to contain extensions, 284 values of {0,0,0,0} imply the file does not contain extensions. 285 Other sequences of values are not currently defined. 286 */ 287 struct nifti1_extender { char extension[4] ; } ; 288 typedef struct nifti1_extender nifti1_extender ; 289 290 /*! \struct nifti1_extension 291 \brief Data structure defining the fields of a header extension. 292 */ 293 struct nifti1_extension { 294 int esize ; /*!< size of extension, in bytes (must be multiple of 16) */ 295 int ecode ; /*!< extension code, one of the NIFTI_ECODE_ values */ 296 char * edata ; /*!< raw data, with no byte swapping (length is esize-8) */ 297 } ; 298 typedef struct nifti1_extension nifti1_extension ; 299 300 /*---------------------------------------------------------------------------*/ 301 /* DATA DIMENSIONALITY (as in ANALYZE 7.5): 302 --------------------------------------- 303 dim[0] = number of dimensions; 304 - if dim[0] is outside range 1..7, then the header information 305 needs to be byte swapped appropriately 306 - ANALYZE supports dim[0] up to 7, but NIFTI-1 reserves 307 dimensions 1,2,3 for space (x,y,z), 4 for time (t), and 308 5,6,7 for anything else needed. 309 310 dim[i] = length of dimension #i, for i=1..dim[0] (must be positive) 311 - also see the discussion of intent_code, far below 312 313 pixdim[i] = voxel width along dimension #i, i=1..dim[0] (positive) 314 - cf. ORIENTATION section below for use of pixdim[0] 315 - the units of pixdim can be specified with the xyzt_units 316 field (also described far below). 317 318 Number of bits per voxel value is in bitpix, which MUST correspond with 319 the datatype field. The total number of bytes in the image data is 320 dim[1] * ... * dim[dim[0]] * bitpix / 8 321 322 In NIFTI-1 files, dimensions 1,2,3 are for space, dimension 4 is for time, 323 and dimension 5 is for storing multiple values at each spatiotemporal 324 voxel. Some examples: 325 - A typical whole-brain FMRI experiment's time series: 326 - dim[0] = 4 327 - dim[1] = 64 pixdim[1] = 3.75 xyzt_units = NIFTI_UNITS_MM 328 - dim[2] = 64 pixdim[2] = 3.75 | NIFTI_UNITS_SEC 329 - dim[3] = 20 pixdim[3] = 5.0 330 - dim[4] = 120 pixdim[4] = 2.0 331 - A typical T1-weighted anatomical volume: 332 - dim[0] = 3 333 - dim[1] = 256 pixdim[1] = 1.0 xyzt_units = NIFTI_UNITS_MM 334 - dim[2] = 256 pixdim[2] = 1.0 335 - dim[3] = 128 pixdim[3] = 1.1 336 - A single slice EPI time series: 337 - dim[0] = 4 338 - dim[1] = 64 pixdim[1] = 3.75 xyzt_units = NIFTI_UNITS_MM 339 - dim[2] = 64 pixdim[2] = 3.75 | NIFTI_UNITS_SEC 340 - dim[3] = 1 pixdim[3] = 5.0 341 - dim[4] = 1200 pixdim[4] = 0.2 342 - A 3-vector stored at each point in a 3D volume: 343 - dim[0] = 5 344 - dim[1] = 256 pixdim[1] = 1.0 xyzt_units = NIFTI_UNITS_MM 345 - dim[2] = 256 pixdim[2] = 1.0 346 - dim[3] = 128 pixdim[3] = 1.1 347 - dim[4] = 1 pixdim[4] = 0.0 348 - dim[5] = 3 intent_code = NIFTI_INTENT_VECTOR 349 - A single time series with a 3x3 matrix at each point: 350 - dim[0] = 5 351 - dim[1] = 1 xyzt_units = NIFTI_UNITS_SEC 352 - dim[2] = 1 353 - dim[3] = 1 354 - dim[4] = 1200 pixdim[4] = 0.2 355 - dim[5] = 9 intent_code = NIFTI_INTENT_GENMATRIX 356 - intent_p1 = intent_p2 = 3.0 (indicates matrix dimensions) 357 -----------------------------------------------------------------------------*/ 358 359 /*---------------------------------------------------------------------------*/ 360 /* DATA STORAGE: 361 ------------ 362 If the magic field is "n+1", then the voxel data is stored in the 363 same file as the header. In this case, the voxel data starts at offset 364 (int)vox_offset into the header file. Thus, vox_offset=352.0 means that 365 the data starts immediately after the NIFTI-1 header. If vox_offset is 366 greater than 352, the NIFTI-1 format does not say much about the 367 contents of the dataset file between the end of the header and the 368 start of the data. 369 370 FILES: 371 ----- 372 If the magic field is "ni1", then the voxel data is stored in the 373 associated ".img" file, starting at offset 0 (i.e., vox_offset is not 374 used in this case, and should be set to 0.0). 375 376 When storing NIFTI-1 datasets in pairs of files, it is customary to name 377 the files in the pattern "name.hdr" and "name.img", as in ANALYZE 7.5. 378 When storing in a single file ("n+1"), the file name should be in 379 the form "name.nii" (the ".nft" and ".nif" suffixes are already taken; 380 cf. http://www.icdatamaster.com/n.html ). 381 382 BYTE ORDERING: 383 ------------- 384 The byte order of the data arrays is presumed to be the same as the byte 385 order of the header (which is determined by examining dim[0]). 386 387 Floating point types are presumed to be stored in IEEE-754 format. 388 -----------------------------------------------------------------------------*/ 389 390 /*---------------------------------------------------------------------------*/ 391 /* DETAILS ABOUT vox_offset: 392 ------------------------ 393 In a .nii file, the vox_offset field value is interpreted as the start 394 location of the image data bytes in that file. In a .hdr/.img file pair, 395 the vox_offset field value is the start location of the image data 396 bytes in the .img file. 397 * If vox_offset is less than 352 in a .nii file, it is equivalent 398 to 352 (i.e., image data never starts before byte #352 in a .nii file). 399 * The default value for vox_offset in a .nii file is 352. 400 * In a .hdr file, the default value for vox_offset is 0. 401 * vox_offset should be an integer multiple of 16; otherwise, some 402 programs may not work properly (e.g., SPM). This is to allow 403 memory-mapped input to be properly byte-aligned. 404 Note that since vox_offset is an IEEE-754 32 bit float (for compatibility 405 with the ANALYZE-7.5 format), it effectively has a 24 bit mantissa. All 406 integers from 0 to 2^24 can be represented exactly in this format, but not 407 all larger integers are exactly storable as IEEE-754 32 bit floats. However, 408 unless you plan to have vox_offset be potentially larger than 16 MB, this 409 should not be an issue. (Actually, any integral multiple of 16 up to 2^27 410 can be represented exactly in this format, which allows for up to 128 MB 411 of random information before the image data. If that isn't enough, then 412 perhaps this format isn't right for you.) 413 414 In a .img file (i.e., image data stored separately from the NIfTI-1 415 header), data bytes between #0 and #vox_offset-1 (inclusive) are completely 416 undefined and unregulated by the NIfTI-1 standard. One potential use of 417 having vox_offset > 0 in the .hdr/.img file pair storage method is to make 418 the .img file be a copy of (or link to) a pre-existing image file in some 419 other format, such as DICOM; then vox_offset would be set to the offset of 420 the image data in this file. (It may not be possible to follow the 421 "multiple-of-16 rule" with an arbitrary external file; using the NIfTI-1 422 format in such a case may lead to a file that is incompatible with software 423 that relies on vox_offset being a multiple of 16.) 424 425 In a .nii file, data bytes between #348 and #vox_offset-1 (inclusive) may 426 be used to store user-defined extra information; similarly, in a .hdr file, 427 any data bytes after byte #347 are available for user-defined extra 428 information. The (very weak) regulation of this extra header data is 429 described elsewhere. 430 -----------------------------------------------------------------------------*/ 431 432 /*---------------------------------------------------------------------------*/ 433 /* DATA SCALING: 434 ------------ 435 If the scl_slope field is nonzero, then each voxel value in the dataset 436 should be scaled as 437 y = scl_slope * x + scl_inter 438 where x = voxel value stored 439 y = "true" voxel value 440 Normally, we would expect this scaling to be used to store "true" floating 441 values in a smaller integer datatype, but that is not required. That is, 442 it is legal to use scaling even if the datatype is a float type (crazy, 443 perhaps, but legal). 444 - However, the scaling is to be ignored if datatype is DT_RGB24. 445 - If datatype is a complex type, then the scaling is to be 446 applied to both the real and imaginary parts. 447 448 The cal_min and cal_max fields (if nonzero) are used for mapping (possibly 449 scaled) dataset values to display colors: 450 - Minimum display intensity (black) corresponds to dataset value cal_min. 451 - Maximum display intensity (white) corresponds to dataset value cal_max. 452 - Dataset values below cal_min should display as black also, and values 453 above cal_max as white. 454 - Colors "black" and "white", of course, may refer to any scalar display 455 scheme (e.g., a color lookup table specified via aux_file). 456 - cal_min and cal_max only make sense when applied to scalar-valued 457 datasets (i.e., dim[0] < 5 or dim[5] = 1). 458 -----------------------------------------------------------------------------*/ 459 460 /*---------------------------------------------------------------------------*/ 461 /* TYPE OF DATA (acceptable values for datatype field): 462 --------------------------------------------------- 463 Values of datatype smaller than 256 are ANALYZE 7.5 compatible. 464 Larger values are NIFTI-1 additions. These are all multiples of 256, so 465 that no bits below position 8 are set in datatype. But there is no need 466 to use only powers-of-2, as the original ANALYZE 7.5 datatype codes do. 467 468 The additional codes are intended to include a complete list of basic 469 scalar types, including signed and unsigned integers from 8 to 64 bits, 470 floats from 32 to 128 bits, and complex (float pairs) from 64 to 256 bits. 471 472 Note that most programs will support only a few of these datatypes! 473 A NIFTI-1 program should fail gracefully (e.g., print a warning message) 474 when it encounters a dataset with a type it doesn't like. 475 -----------------------------------------------------------------------------*/ 476 477 #undef DT_UNKNOWN /* defined in dirent.h on some Unix systems */ 478 479 /*! \defgroup NIFTI1_DATATYPES 480 \brief nifti1 datatype codes 481 @{ 482 */ 483 /*--- the original ANALYZE 7.5 type codes ---*/ 484 #define DT_NONE 0 485 #define DT_UNKNOWN 0 /* what it says, dude */ 486 #define DT_BINARY 1 /* binary (1 bit/voxel) */ 487 #define DT_UNSIGNED_CHAR 2 /* unsigned char (8 bits/voxel) */ 488 #define DT_SIGNED_SHORT 4 /* signed short (16 bits/voxel) */ 489 #define DT_SIGNED_INT 8 /* signed int (32 bits/voxel) */ 490 #define DT_FLOAT 16 /* float (32 bits/voxel) */ 491 #define DT_COMPLEX 32 /* complex (64 bits/voxel) */ 492 #define DT_DOUBLE 64 /* double (64 bits/voxel) */ 493 #define DT_RGB 128 /* RGB triple (24 bits/voxel) */ 494 #define DT_ALL 255 /* not very useful (?) */ 495 496 /*----- another set of names for the same ---*/ 497 #define DT_UINT8 2 498 #define DT_INT16 4 499 #define DT_INT32 8 500 #define DT_FLOAT32 16 501 #define DT_COMPLEX64 32 502 #define DT_FLOAT64 64 503 #define DT_RGB24 128 504 505 /*------------------- new codes for NIFTI ---*/ 506 #define DT_INT8 256 /* signed char (8 bits) */ 507 #define DT_UINT16 512 /* unsigned short (16 bits) */ 508 #define DT_UINT32 768 /* unsigned int (32 bits) */ 509 #define DT_INT64 1024 /* long long (64 bits) */ 510 #define DT_UINT64 1280 /* unsigned long long (64 bits) */ 511 #define DT_FLOAT128 1536 /* long double (128 bits) */ 512 #define DT_COMPLEX128 1792 /* double pair (128 bits) */ 513 #define DT_COMPLEX256 2048 /* long double pair (256 bits) */ 514 #define DT_RGBA32 2304 /* 4 byte RGBA (32 bits/voxel) */ 515 /* @} */ 516 517 518 /*------- aliases for all the above codes ---*/ 519 520 /*! \defgroup NIFTI1_DATATYPE_ALIASES 521 \brief aliases for the nifti1 datatype codes 522 @{ 523 */ 524 /*! unsigned char. */ 525 #define NIFTI_TYPE_UINT8 2 526 /*! signed short. */ 527 #define NIFTI_TYPE_INT16 4 528 /*! signed int. */ 529 #define NIFTI_TYPE_INT32 8 530 /*! 32 bit float. */ 531 #define NIFTI_TYPE_FLOAT32 16 532 /*! 64 bit complex = 2 32 bit floats. */ 533 #define NIFTI_TYPE_COMPLEX64 32 534 /*! 64 bit float = double. */ 535 #define NIFTI_TYPE_FLOAT64 64 536 /*! 3 8 bit bytes. */ 537 #define NIFTI_TYPE_RGB24 128 538 /*! signed char. */ 539 #define NIFTI_TYPE_INT8 256 540 /*! unsigned short. */ 541 #define NIFTI_TYPE_UINT16 512 542 /*! unsigned int. */ 543 #define NIFTI_TYPE_UINT32 768 544 /*! signed long long. */ 545 #define NIFTI_TYPE_INT64 1024 546 /*! unsigned long long. */ 547 #define NIFTI_TYPE_UINT64 1280 548 /*! 128 bit float = long double. */ 549 #define NIFTI_TYPE_FLOAT128 1536 550 /*! 128 bit complex = 2 64 bit floats. */ 551 #define NIFTI_TYPE_COMPLEX128 1792 552 /*! 256 bit complex = 2 128 bit floats */ 553 #define NIFTI_TYPE_COMPLEX256 2048 554 /*! 4 8 bit bytes. */ 555 #define NIFTI_TYPE_RGBA32 2304 556 /* @} */ 557 558 /*-------- sample typedefs for complicated types ---*/ 559 #if 0 560 typedef struct { float r,i; } complex_float ; 561 typedef struct { double r,i; } complex_double ; 562 typedef struct { long double r,i; } complex_longdouble ; 563 typedef struct { unsigned char r,g,b; } rgb_byte ; 564 #endif 565 566 /*---------------------------------------------------------------------------*/ 567 /* INTERPRETATION OF VOXEL DATA: 568 ---------------------------- 569 The intent_code field can be used to indicate that the voxel data has 570 some particular meaning. In particular, a large number of codes is 571 given to indicate that the the voxel data should be interpreted as 572 being drawn from a given probability distribution. 573 574 VECTOR-VALUED DATASETS: 575 ---------------------- 576 The 5th dimension of the dataset, if present (i.e., dim[0]=5 and 577 dim[5] > 1), contains multiple values (e.g., a vector) to be stored 578 at each spatiotemporal location. For example, the header values 579 - dim[0] = 5 580 - dim[1] = 64 581 - dim[2] = 64 582 - dim[3] = 20 583 - dim[4] = 1 (indicates no time axis) 584 - dim[5] = 3 585 - datatype = DT_FLOAT 586 - intent_code = NIFTI_INTENT_VECTOR 587 mean that this dataset should be interpreted as a 3D volume (64x64x20), 588 with a 3-vector of floats defined at each point in the 3D grid. 589 590 A program reading a dataset with a 5th dimension may want to reformat 591 the image data to store each voxels' set of values together in a struct 592 or array. This programming detail, however, is beyond the scope of the 593 NIFTI-1 file specification! Uses of dimensions 6 and 7 are also not 594 specified here. 595 596 STATISTICAL PARAMETRIC DATASETS (i.e., SPMs): 597 -------------------------------------------- 598 Values of intent_code from NIFTI_FIRST_STATCODE to NIFTI_LAST_STATCODE 599 (inclusive) indicate that the numbers in the dataset should be interpreted 600 as being drawn from a given distribution. Most such distributions have 601 auxiliary parameters (e.g., NIFTI_INTENT_TTEST has 1 DOF parameter). 602 603 If the dataset DOES NOT have a 5th dimension, then the auxiliary parameters 604 are the same for each voxel, and are given in header fields intent_p1, 605 intent_p2, and intent_p3. 606 607 If the dataset DOES have a 5th dimension, then the auxiliary parameters 608 are different for each voxel. For example, the header values 609 - dim[0] = 5 610 - dim[1] = 128 611 - dim[2] = 128 612 - dim[3] = 1 (indicates a single slice) 613 - dim[4] = 1 (indicates no time axis) 614 - dim[5] = 2 615 - datatype = DT_FLOAT 616 - intent_code = NIFTI_INTENT_TTEST 617 mean that this is a 2D dataset (128x128) of t-statistics, with the 618 t-statistic being in the first "plane" of data and the degrees-of-freedom 619 parameter being in the second "plane" of data. 620 621 If the dataset 5th dimension is used to store the voxel-wise statistical 622 parameters, then dim[5] must be 1 plus the number of parameters required 623 by that distribution (e.g., intent_code=NIFTI_INTENT_TTEST implies dim[5] 624 must be 2, as in the example just above). 625 626 Note: intent_code values 2..10 are compatible with AFNI 1.5x (which is 627 why there is no code with value=1, which is obsolescent in AFNI). 628 629 OTHER INTENTIONS: 630 ---------------- 631 The purpose of the intent_* fields is to help interpret the values 632 stored in the dataset. Some non-statistical values for intent_code 633 and conventions are provided for storing other complex data types. 634 635 The intent_name field provides space for a 15 character (plus 0 byte) 636 'name' string for the type of data stored. Examples: 637 - intent_code = NIFTI_INTENT_ESTIMATE; intent_name = "T1"; 638 could be used to signify that the voxel values are estimates of the 639 NMR parameter T1. 640 - intent_code = NIFTI_INTENT_TTEST; intent_name = "House"; 641 could be used to signify that the voxel values are t-statistics 642 for the significance of 'activation' response to a House stimulus. 643 - intent_code = NIFTI_INTENT_DISPVECT; intent_name = "ToMNI152"; 644 could be used to signify that the voxel values are a displacement 645 vector that transforms each voxel (x,y,z) location to the 646 corresponding location in the MNI152 standard brain. 647 - intent_code = NIFTI_INTENT_SYMMATRIX; intent_name = "DTI"; 648 could be used to signify that the voxel values comprise a diffusion 649 tensor image. 650 651 If no data name is implied or needed, intent_name[0] should be set to 0. 652 -----------------------------------------------------------------------------*/ 653 654 /*! default: no intention is indicated in the header. */ 655 656 #define NIFTI_INTENT_NONE 0 657 658 /*-------- These codes are for probability distributions ---------------*/ 659 /* Most distributions have a number of parameters, 660 below denoted by p1, p2, and p3, and stored in 661 - intent_p1, intent_p2, intent_p3 if dataset doesn't have 5th dimension 662 - image data array if dataset does have 5th dimension 663 664 Functions to compute with many of the distributions below can be found 665 in the CDF library from U Texas. 666 667 Formulas for and discussions of these distributions can be found in the 668 following books: 669 670 [U] Univariate Discrete Distributions, 671 NL Johnson, S Kotz, AW Kemp. 672 673 [C1] Continuous Univariate Distributions, vol. 1, 674 NL Johnson, S Kotz, N Balakrishnan. 675 676 [C2] Continuous Univariate Distributions, vol. 2, 677 NL Johnson, S Kotz, N Balakrishnan. */ 678 /*----------------------------------------------------------------------*/ 679 680 /*! [C2, chap 32] Correlation coefficient R (1 param): 681 p1 = degrees of freedom 682 R/sqrt(1-R*R) is t-distributed with p1 DOF. */ 683 684 /*! \defgroup NIFTI1_INTENT_CODES 685 \brief nifti1 intent codes, to describe intended meaning of dataset contents 686 @{ 687 */ 688 #define NIFTI_INTENT_CORREL 2 689 690 /*! [C2, chap 28] Student t statistic (1 param): p1 = DOF. */ 691 692 #define NIFTI_INTENT_TTEST 3 693 694 /*! [C2, chap 27] Fisher F statistic (2 params): 695 p1 = numerator DOF, p2 = denominator DOF. */ 696 697 #define NIFTI_INTENT_FTEST 4 698 699 /*! [C1, chap 13] Standard normal (0 params): Density = N(0,1). */ 700 701 #define NIFTI_INTENT_ZSCORE 5 702 703 /*! [C1, chap 18] Chi-squared (1 param): p1 = DOF. 704 Density(x) proportional to exp(-x/2) * x^(p1/2-1). */ 705 706 #define NIFTI_INTENT_CHISQ 6 707 708 /*! [C2, chap 25] Beta distribution (2 params): p1=a, p2=b. 709 Density(x) proportional to x^(a-1) * (1-x)^(b-1). */ 710 711 #define NIFTI_INTENT_BETA 7 712 713 /*! [U, chap 3] Binomial distribution (2 params): 714 p1 = number of trials, p2 = probability per trial. 715 Prob(x) = (p1 choose x) * p2^x * (1-p2)^(p1-x), for x=0,1,...,p1. */ 716 717 #define NIFTI_INTENT_BINOM 8 718 719 /*! [C1, chap 17] Gamma distribution (2 params): 720 p1 = shape, p2 = scale. 721 Density(x) proportional to x^(p1-1) * exp(-p2*x). */ 722 723 #define NIFTI_INTENT_GAMMA 9 724 725 /*! [U, chap 4] Poisson distribution (1 param): p1 = mean. 726 Prob(x) = exp(-p1) * p1^x / x! , for x=0,1,2,.... */ 727 728 #define NIFTI_INTENT_POISSON 10 729 730 /*! [C1, chap 13] Normal distribution (2 params): 731 p1 = mean, p2 = standard deviation. */ 732 733 #define NIFTI_INTENT_NORMAL 11 734 735 /*! [C2, chap 30] Noncentral F statistic (3 params): 736 p1 = numerator DOF, p2 = denominator DOF, 737 p3 = numerator noncentrality parameter. */ 738 739 #define NIFTI_INTENT_FTEST_NONC 12 740 741 /*! [C2, chap 29] Noncentral chi-squared statistic (2 params): 742 p1 = DOF, p2 = noncentrality parameter. */ 743 744 #define NIFTI_INTENT_CHISQ_NONC 13 745 746 /*! [C2, chap 23] Logistic distribution (2 params): 747 p1 = location, p2 = scale. 748 Density(x) proportional to sech^2((x-p1)/(2*p2)). */ 749 750 #define NIFTI_INTENT_LOGISTIC 14 751 752 /*! [C2, chap 24] Laplace distribution (2 params): 753 p1 = location, p2 = scale. 754 Density(x) proportional to exp(-abs(x-p1)/p2). */ 755 756 #define NIFTI_INTENT_LAPLACE 15 757 758 /*! [C2, chap 26] Uniform distribution: p1 = lower end, p2 = upper end. */ 759 760 #define NIFTI_INTENT_UNIFORM 16 761 762 /*! [C2, chap 31] Noncentral t statistic (2 params): 763 p1 = DOF, p2 = noncentrality parameter. */ 764 765 #define NIFTI_INTENT_TTEST_NONC 17 766 767 /*! [C1, chap 21] Weibull distribution (3 params): 768 p1 = location, p2 = scale, p3 = power. 769 Density(x) proportional to 770 ((x-p1)/p2)^(p3-1) * exp(-((x-p1)/p2)^p3) for x > p1. */ 771 772 #define NIFTI_INTENT_WEIBULL 18 773 774 /*! [C1, chap 18] Chi distribution (1 param): p1 = DOF. 775 Density(x) proportional to x^(p1-1) * exp(-x^2/2) for x > 0. 776 p1 = 1 = 'half normal' distribution 777 p1 = 2 = Rayleigh distribution 778 p1 = 3 = Maxwell-Boltzmann distribution. */ 779 780 #define NIFTI_INTENT_CHI 19 781 782 /*! [C1, chap 15] Inverse Gaussian (2 params): 783 p1 = mu, p2 = lambda 784 Density(x) proportional to 785 exp(-p2*(x-p1)^2/(2*p1^2*x)) / x^3 for x > 0. */ 786 787 #define NIFTI_INTENT_INVGAUSS 20 788 789 /*! [C2, chap 22] Extreme value type I (2 params): 790 p1 = location, p2 = scale 791 cdf(x) = exp(-exp(-(x-p1)/p2)). */ 792 793 #define NIFTI_INTENT_EXTVAL 21 794 795 /*! Data is a 'p-value' (no params). */ 796 797 #define NIFTI_INTENT_PVAL 22 798 799 /*! Data is ln(p-value) (no params). 800 To be safe, a program should compute p = exp(-abs(this_value)). 801 The nifti_stats.c library returns this_value 802 as positive, so that this_value = -log(p). */ 803 804 805 #define NIFTI_INTENT_LOGPVAL 23 806 807 /*! Data is log10(p-value) (no params). 808 To be safe, a program should compute p = pow(10.,-abs(this_value)). 809 The nifti_stats.c library returns this_value 810 as positive, so that this_value = -log10(p). */ 811 812 #define NIFTI_INTENT_LOG10PVAL 24 813 814 /*! Smallest intent_code that indicates a statistic. */ 815 816 #define NIFTI_FIRST_STATCODE 2 817 818 /*! Largest intent_code that indicates a statistic. */ 819 820 #define NIFTI_LAST_STATCODE 24 821 822 /*---------- these values for intent_code aren't for statistics ----------*/ 823 824 /*! To signify that the value at each voxel is an estimate 825 of some parameter, set intent_code = NIFTI_INTENT_ESTIMATE. 826 The name of the parameter may be stored in intent_name. */ 827 828 #define NIFTI_INTENT_ESTIMATE 1001 829 830 /*! To signify that the value at each voxel is an index into 831 some set of labels, set intent_code = NIFTI_INTENT_LABEL. 832 The filename with the labels may stored in aux_file. */ 833 834 #define NIFTI_INTENT_LABEL 1002 835 836 /*! To signify that the value at each voxel is an index into the 837 NeuroNames labels set, set intent_code = NIFTI_INTENT_NEURONAME. */ 838 839 #define NIFTI_INTENT_NEURONAME 1003 840 841 /*! To store an M x N matrix at each voxel: 842 - dataset must have a 5th dimension (dim[0]=5 and dim[5]>1) 843 - intent_code must be NIFTI_INTENT_GENMATRIX 844 - dim[5] must be M*N 845 - intent_p1 must be M (in float format) 846 - intent_p2 must be N (ditto) 847 - the matrix values A[i][[j] are stored in row-order: 848 - A[0][0] A[0][1] ... A[0][N-1] 849 - A[1][0] A[1][1] ... A[1][N-1] 850 - etc., until 851 - A[M-1][0] A[M-1][1] ... A[M-1][N-1] */ 852 853 #define NIFTI_INTENT_GENMATRIX 1004 854 855 /*! To store an NxN symmetric matrix at each voxel: 856 - dataset must have a 5th dimension 857 - intent_code must be NIFTI_INTENT_SYMMATRIX 858 - dim[5] must be N*(N+1)/2 859 - intent_p1 must be N (in float format) 860 - the matrix values A[i][[j] are stored in row-order: 861 - A[0][0] 862 - A[1][0] A[1][1] 863 - A[2][0] A[2][1] A[2][2] 864 - etc.: row-by-row */ 865 866 #define NIFTI_INTENT_SYMMATRIX 1005 867 868 /*! To signify that the vector value at each voxel is to be taken 869 as a displacement field or vector: 870 - dataset must have a 5th dimension 871 - intent_code must be NIFTI_INTENT_DISPVECT 872 - dim[5] must be the dimensionality of the displacment 873 vector (e.g., 3 for spatial displacement, 2 for in-plane) */ 874 875 #define NIFTI_INTENT_DISPVECT 1006 /* specifically for displacements */ 876 #define NIFTI_INTENT_VECTOR 1007 /* for any other type of vector */ 877 878 /*! To signify that the vector value at each voxel is really a 879 spatial coordinate (e.g., the vertices or nodes of a surface mesh): 880 - dataset must have a 5th dimension 881 - intent_code must be NIFTI_INTENT_POINTSET 882 - dim[0] = 5 883 - dim[1] = number of points 884 - dim[2] = dim[3] = dim[4] = 1 885 - dim[5] must be the dimensionality of space (e.g., 3 => 3D space). 886 - intent_name may describe the object these points come from 887 (e.g., "pial", "gray/white" , "EEG", "MEG"). */ 888 889 #define NIFTI_INTENT_POINTSET 1008 890 891 /*! To signify that the vector value at each voxel is really a triple 892 of indexes (e.g., forming a triangle) from a pointset dataset: 893 - dataset must have a 5th dimension 894 - intent_code must be NIFTI_INTENT_TRIANGLE 895 - dim[0] = 5 896 - dim[1] = number of triangles 897 - dim[2] = dim[3] = dim[4] = 1 898 - dim[5] = 3 899 - datatype should be an integer type (preferably DT_INT32) 900 - the data values are indexes (0,1,...) into a pointset dataset. */ 901 902 #define NIFTI_INTENT_TRIANGLE 1009 903 904 /*! To signify that the vector value at each voxel is a quaternion: 905 - dataset must have a 5th dimension 906 - intent_code must be NIFTI_INTENT_QUATERNION 907 - dim[0] = 5 908 - dim[5] = 4 909 - datatype should be a floating point type */ 910 911 #define NIFTI_INTENT_QUATERNION 1010 912 913 /*! Dimensionless value - no params - although, as in _ESTIMATE 914 the name of the parameter may be stored in intent_name. */ 915 916 #define NIFTI_INTENT_DIMLESS 1011 917 918 /*---------- these values apply to GIFTI datasets ----------*/ 919 920 /*! To signify that the value at each location is from a time series. */ 921 922 #define NIFTI_INTENT_TIME_SERIES 2001 923 924 /*! To signify that the value at each location is a node index, from 925 a complete surface dataset. */ 926 927 #define NIFTI_INTENT_NODE_INDEX 2002 928 929 /*! To signify that the vector value at each location is an RGB triplet, 930 of whatever type. 931 - dataset must have a 5th dimension 932 - dim[0] = 5 933 - dim[1] = number of nodes 934 - dim[2] = dim[3] = dim[4] = 1 935 - dim[5] = 3 936 */ 937 938 #define NIFTI_INTENT_RGB_VECTOR 2003 939 940 /*! To signify that the vector value at each location is a 4 valued RGBA 941 vector, of whatever type. 942 - dataset must have a 5th dimension 943 - dim[0] = 5 944 - dim[1] = number of nodes 945 - dim[2] = dim[3] = dim[4] = 1 946 - dim[5] = 4 947 */ 948 949 #define NIFTI_INTENT_RGBA_VECTOR 2004 950 951 /*! To signify that the value at each location is a shape value, such 952 as the curvature. */ 953 954 #define NIFTI_INTENT_SHAPE 2005 955 956 /* @} */ 957 958 /*---------------------------------------------------------------------------*/ 959 /* 3D IMAGE (VOLUME) ORIENTATION AND LOCATION IN SPACE: 960 --------------------------------------------------- 961 There are 3 different methods by which continuous coordinates can 962 attached to voxels. The discussion below emphasizes 3D volumes, and 963 the continuous coordinates are referred to as (x,y,z). The voxel 964 index coordinates (i.e., the array indexes) are referred to as (i,j,k), 965 with valid ranges: 966 i = 0 .. dim[1]-1 967 j = 0 .. dim[2]-1 (if dim[0] >= 2) 968 k = 0 .. dim[3]-1 (if dim[0] >= 3) 969 The (x,y,z) coordinates refer to the CENTER of a voxel. In methods 970 2 and 3, the (x,y,z) axes refer to a subject-based coordinate system, 971 with 972 +x = Right +y = Anterior +z = Superior. 973 This is a right-handed coordinate system. However, the exact direction 974 these axes point with respect to the subject depends on qform_code 975 (Method 2) and sform_code (Method 3). 976 977 N.B.: The i index varies most rapidly, j index next, k index slowest. 978 Thus, voxel (i,j,k) is stored starting at location 979 (i + j*dim[1] + k*dim[1]*dim[2]) * (bitpix/8) 980 into the dataset array. 981 982 N.B.: The ANALYZE 7.5 coordinate system is 983 +x = Left +y = Anterior +z = Superior 984 which is a left-handed coordinate system. This backwardness is 985 too difficult to tolerate, so this NIFTI-1 standard specifies the 986 coordinate order which is most common in functional neuroimaging. 987 988 N.B.: The 3 methods below all give the locations of the voxel centers 989 in the (x,y,z) coordinate system. In many cases, programs will wish 990 to display image data on some other grid. In such a case, the program 991 will need to convert its desired (x,y,z) values into (i,j,k) values 992 in order to extract (or interpolate) the image data. This operation 993 would be done with the inverse transformation to those described below. 994 995 N.B.: Method 2 uses a factor 'qfac' which is either -1 or 1; qfac is 996 stored in the otherwise unused pixdim[0]. If pixdim[0]=0.0 (which 997 should not occur), we take qfac=1. Of course, pixdim[0] is only used 998 when reading a NIFTI-1 header, not when reading an ANALYZE 7.5 header. 999 1000 N.B.: The units of (x,y,z) can be specified using the xyzt_units field. 1001 1002 METHOD 1 (the "old" way, used only when qform_code = 0): 1003 ------------------------------------------------------- 1004 The coordinate mapping from (i,j,k) to (x,y,z) is the ANALYZE 1005 7.5 way. This is a simple scaling relationship: 1006 1007 x = pixdim[1] * i 1008 y = pixdim[2] * j 1009 z = pixdim[3] * k 1010 1011 No particular spatial orientation is attached to these (x,y,z) 1012 coordinates. (NIFTI-1 does not have the ANALYZE 7.5 orient field, 1013 which is not general and is often not set properly.) This method 1014 is not recommended, and is present mainly for compatibility with 1015 ANALYZE 7.5 files. 1016 1017 METHOD 2 (used when qform_code > 0, which should be the "normal" case): 1018 --------------------------------------------------------------------- 1019 The (x,y,z) coordinates are given by the pixdim[] scales, a rotation 1020 matrix, and a shift. This method is intended to represent 1021 "scanner-anatomical" coordinates, which are often embedded in the 1022 image header (e.g., DICOM fields (0020,0032), (0020,0037), (0028,0030), 1023 and (0018,0050)), and represent the nominal orientation and location of 1024 the data. This method can also be used to represent "aligned" 1025 coordinates, which would typically result from some post-acquisition 1026 alignment of the volume to a standard orientation (e.g., the same 1027 subject on another day, or a rigid rotation to true anatomical 1028 orientation from the tilted position of the subject in the scanner). 1029 The formula for (x,y,z) in terms of header parameters and (i,j,k) is: 1030 1031 [ x ] [ R11 R12 R13 ] [ pixdim[1] * i ] [ qoffset_x ] 1032 [ y ] = [ R21 R22 R23 ] [ pixdim[2] * j ] + [ qoffset_y ] 1033 [ z ] [ R31 R32 R33 ] [ qfac * pixdim[3] * k ] [ qoffset_z ] 1034 1035 The qoffset_* shifts are in the NIFTI-1 header. Note that the center 1036 of the (i,j,k)=(0,0,0) voxel (first value in the dataset array) is 1037 just (x,y,z)=(qoffset_x,qoffset_y,qoffset_z). 1038 1039 The rotation matrix R is calculated from the quatern_* parameters. 1040 This calculation is described below. 1041 1042 The scaling factor qfac is either 1 or -1. The rotation matrix R 1043 defined by the quaternion parameters is "proper" (has determinant 1). 1044 This may not fit the needs of the data; for example, if the image 1045 grid is 1046 i increases from Left-to-Right 1047 j increases from Anterior-to-Posterior 1048 k increases from Inferior-to-Superior 1049 Then (i,j,k) is a left-handed triple. In this example, if qfac=1, 1050 the R matrix would have to be 1051 1052 [ 1 0 0 ] 1053 [ 0 -1 0 ] which is "improper" (determinant = -1). 1054 [ 0 0 1 ] 1055 1056 If we set qfac=-1, then the R matrix would be 1057 1058 [ 1 0 0 ] 1059 [ 0 -1 0 ] which is proper. 1060 [ 0 0 -1 ] 1061 1062 This R matrix is represented by quaternion [a,b,c,d] = [0,1,0,0] 1063 (which encodes a 180 degree rotation about the x-axis). 1064 1065 METHOD 3 (used when sform_code > 0): 1066 ----------------------------------- 1067 The (x,y,z) coordinates are given by a general affine transformation 1068 of the (i,j,k) indexes: 1069 1070 x = srow_x[0] * i + srow_x[1] * j + srow_x[2] * k + srow_x[3] 1071 y = srow_y[0] * i + srow_y[1] * j + srow_y[2] * k + srow_y[3] 1072 z = srow_z[0] * i + srow_z[1] * j + srow_z[2] * k + srow_z[3] 1073 1074 The srow_* vectors are in the NIFTI_1 header. Note that no use is 1075 made of pixdim[] in this method. 1076 1077 WHY 3 METHODS? 1078 -------------- 1079 Method 1 is provided only for backwards compatibility. The intention 1080 is that Method 2 (qform_code > 0) represents the nominal voxel locations 1081 as reported by the scanner, or as rotated to some fiducial orientation and 1082 location. Method 3, if present (sform_code > 0), is to be used to give 1083 the location of the voxels in some standard space. The sform_code 1084 indicates which standard space is present. Both methods 2 and 3 can be 1085 present, and be useful in different contexts (method 2 for displaying the 1086 data on its original grid; method 3 for displaying it on a standard grid). 1087 1088 In this scheme, a dataset would originally be set up so that the 1089 Method 2 coordinates represent what the scanner reported. Later, 1090 a registration to some standard space can be computed and inserted 1091 in the header. Image display software can use either transform, 1092 depending on its purposes and needs. 1093 1094 In Method 2, the origin of coordinates would generally be whatever 1095 the scanner origin is; for example, in MRI, (0,0,0) is the center 1096 of the gradient coil. 1097 1098 In Method 3, the origin of coordinates would depend on the value 1099 of sform_code; for example, for the Talairach coordinate system, 1100 (0,0,0) corresponds to the Anterior Commissure. 1101 1102 QUATERNION REPRESENTATION OF ROTATION MATRIX (METHOD 2) 1103 ------------------------------------------------------- 1104 The orientation of the (x,y,z) axes relative to the (i,j,k) axes 1105 in 3D space is specified using a unit quaternion [a,b,c,d], where 1106 a*a+b*b+c*c+d*d=1. The (b,c,d) values are all that is needed, since 1107 we require that a = sqrt(1.0-(b*b+c*c+d*d)) be nonnegative. The (b,c,d) 1108 values are stored in the (quatern_b,quatern_c,quatern_d) fields. 1109 1110 The quaternion representation is chosen for its compactness in 1111 representing rotations. The (proper) 3x3 rotation matrix that 1112 corresponds to [a,b,c,d] is 1113 1114 [ a*a+b*b-c*c-d*d 2*b*c-2*a*d 2*b*d+2*a*c ] 1115 R = [ 2*b*c+2*a*d a*a+c*c-b*b-d*d 2*c*d-2*a*b ] 1116 [ 2*b*d-2*a*c 2*c*d+2*a*b a*a+d*d-c*c-b*b ] 1117 1118 [ R11 R12 R13 ] 1119 = [ R21 R22 R23 ] 1120 [ R31 R32 R33 ] 1121 1122 If (p,q,r) is a unit 3-vector, then rotation of angle h about that 1123 direction is represented by the quaternion 1124 1125 [a,b,c,d] = [cos(h/2), p*sin(h/2), q*sin(h/2), r*sin(h/2)]. 1126 1127 Requiring a >= 0 is equivalent to requiring -Pi <= h <= Pi. (Note that 1128 [-a,-b,-c,-d] represents the same rotation as [a,b,c,d]; there are 2 1129 quaternions that can be used to represent a given rotation matrix R.) 1130 To rotate a 3-vector (x,y,z) using quaternions, we compute the 1131 quaternion product 1132 1133 [0,x',y',z'] = [a,b,c,d] * [0,x,y,z] * [a,-b,-c,-d] 1134 1135 which is equivalent to the matrix-vector multiply 1136 1137 [ x' ] [ x ] 1138 [ y' ] = R [ y ] (equivalence depends on a*a+b*b+c*c+d*d=1) 1139 [ z' ] [ z ] 1140 1141 Multiplication of 2 quaternions is defined by the following: 1142 1143 [a,b,c,d] = a*1 + b*I + c*J + d*K 1144 where 1145 I*I = J*J = K*K = -1 (I,J,K are square roots of -1) 1146 I*J = K J*K = I K*I = J 1147 J*I = -K K*J = -I I*K = -J (not commutative!) 1148 For example 1149 [a,b,0,0] * [0,0,0,1] = [0,0,-b,a] 1150 since this expands to 1151 (a+b*I)*(K) = (a*K+b*I*K) = (a*K-b*J). 1152 1153 The above formula shows how to go from quaternion (b,c,d) to 1154 rotation matrix and direction cosines. Conversely, given R, 1155 we can compute the fields for the NIFTI-1 header by 1156 1157 a = 0.5 * sqrt(1+R11+R22+R33) (not stored) 1158 b = 0.25 * (R32-R23) / a => quatern_b 1159 c = 0.25 * (R13-R31) / a => quatern_c 1160 d = 0.25 * (R21-R12) / a => quatern_d 1161 1162 If a=0 (a 180 degree rotation), alternative formulas are needed. 1163 See the nifti1_io.c function mat44_to_quatern() for an implementation 1164 of the various cases in converting R to [a,b,c,d]. 1165 1166 Note that R-transpose (= R-inverse) would lead to the quaternion 1167 [a,-b,-c,-d]. 1168 1169 The choice to specify the qoffset_x (etc.) values in the final 1170 coordinate system is partly to make it easy to convert DICOM images to 1171 this format. The DICOM attribute "Image Position (Patient)" (0020,0032) 1172 stores the (Xd,Yd,Zd) coordinates of the center of the first voxel. 1173 Here, (Xd,Yd,Zd) refer to DICOM coordinates, and Xd=-x, Yd=-y, Zd=z, 1174 where (x,y,z) refers to the NIFTI coordinate system discussed above. 1175 (i.e., DICOM +Xd is Left, +Yd is Posterior, +Zd is Superior, 1176 whereas +x is Right, +y is Anterior , +z is Superior. ) 1177 Thus, if the (0020,0032) DICOM attribute is extracted into (px,py,pz), then 1178 qoffset_x = -px qoffset_y = -py qoffset_z = pz 1179 is a reasonable setting when qform_code=NIFTI_XFORM_SCANNER_ANAT. 1180 1181 That is, DICOM's coordinate system is 180 degrees rotated about the z-axis 1182 from the neuroscience/NIFTI coordinate system. To transform between DICOM 1183 and NIFTI, you just have to negate the x- and y-coordinates. 1184 1185 The DICOM attribute (0020,0037) "Image Orientation (Patient)" gives the 1186 orientation of the x- and y-axes of the image data in terms of 2 3-vectors. 1187 The first vector is a unit vector along the x-axis, and the second is 1188 along the y-axis. If the (0020,0037) attribute is extracted into the 1189 value (xa,xb,xc,ya,yb,yc), then the first two columns of the R matrix 1190 would be 1191 [ -xa -ya ] 1192 [ -xb -yb ] 1193 [ xc yc ] 1194 The negations are because DICOM's x- and y-axes are reversed relative 1195 to NIFTI's. The third column of the R matrix gives the direction of 1196 displacement (relative to the subject) along the slice-wise direction. 1197 This orientation is not encoded in the DICOM standard in a simple way; 1198 DICOM is mostly concerned with 2D images. The third column of R will be 1199 either the cross-product of the first 2 columns or its negative. It is 1200 possible to infer the sign of the 3rd column by examining the coordinates 1201 in DICOM attribute (0020,0032) "Image Position (Patient)" for successive 1202 slices. However, this method occasionally fails for reasons that I 1203 (RW Cox) do not understand. 1204 -----------------------------------------------------------------------------*/ 1205 1206 /* [qs]form_code value: */ /* x,y,z coordinate system refers to: */ 1207 /*-----------------------*/ /*---------------------------------------*/ 1208 1209 /*! \defgroup NIFTI1_XFORM_CODES 1210 \brief nifti1 xform codes to describe the "standard" coordinate system 1211 @{ 1212 */ 1213 /*! Arbitrary coordinates (Method 1). */ 1214 1215 #define NIFTI_XFORM_UNKNOWN 0 1216 1217 /*! Scanner-based anatomical coordinates */ 1218 1219 #define NIFTI_XFORM_SCANNER_ANAT 1 1220 1221 /*! Coordinates aligned to another file's, 1222 or to anatomical "truth". */ 1223 1224 #define NIFTI_XFORM_ALIGNED_ANAT 2 1225 1226 /*! Coordinates aligned to Talairach- 1227 Tournoux Atlas; (0,0,0)=AC, etc. */ 1228 1229 #define NIFTI_XFORM_TALAIRACH 3 1230 1231 /*! MNI 152 normalized coordinates. */ 1232 1233 #define NIFTI_XFORM_MNI_152 4 1234 /* @} */ 1235 1236 /*---------------------------------------------------------------------------*/ 1237 /* UNITS OF SPATIAL AND TEMPORAL DIMENSIONS: 1238 ---------------------------------------- 1239 The codes below can be used in xyzt_units to indicate the units of pixdim. 1240 As noted earlier, dimensions 1,2,3 are for x,y,z; dimension 4 is for 1241 time (t). 1242 - If dim[4]=1 or dim[0] < 4, there is no time axis. 1243 - A single time series (no space) would be specified with 1244 - dim[0] = 4 (for scalar data) or dim[0] = 5 (for vector data) 1245 - dim[1] = dim[2] = dim[3] = 1 1246 - dim[4] = number of time points 1247 - pixdim[4] = time step 1248 - xyzt_units indicates units of pixdim[4] 1249 - dim[5] = number of values stored at each time point 1250 1251 Bits 0..2 of xyzt_units specify the units of pixdim[1..3] 1252 (e.g., spatial units are values 1..7). 1253 Bits 3..5 of xyzt_units specify the units of pixdim[4] 1254 (e.g., temporal units are multiples of 8). 1255 1256 This compression of 2 distinct concepts into 1 byte is due to the 1257 limited space available in the 348 byte ANALYZE 7.5 header. The 1258 macros XYZT_TO_SPACE and XYZT_TO_TIME can be used to mask off the 1259 undesired bits from the xyzt_units fields, leaving "pure" space 1260 and time codes. Inversely, the macro SPACE_TIME_TO_XYZT can be 1261 used to assemble a space code (0,1,2,...,7) with a time code 1262 (0,8,16,32,...,56) into the combined value for xyzt_units. 1263 1264 Note that codes are provided to indicate the "time" axis units are 1265 actually frequency in Hertz (_HZ), in part-per-million (_PPM) 1266 or in radians-per-second (_RADS). 1267 1268 The toffset field can be used to indicate a nonzero start point for 1269 the time axis. That is, time point #m is at t=toffset+m*pixdim[4] 1270 for m=0..dim[4]-1. 1271 -----------------------------------------------------------------------------*/ 1272 1273 /*! \defgroup NIFTI1_UNITS 1274 \brief nifti1 units codes to describe the unit of measurement for 1275 each dimension of the dataset 1276 @{ 1277 */ 1278 /*! NIFTI code for unspecified units. */ 1279 #define NIFTI_UNITS_UNKNOWN 0 1280 1281 /** Space codes are multiples of 1. **/ 1282 /*! NIFTI code for meters. */ 1283 #define NIFTI_UNITS_METER 1 1284 /*! NIFTI code for millimeters. */ 1285 #define NIFTI_UNITS_MM 2 1286 /*! NIFTI code for micrometers. */ 1287 #define NIFTI_UNITS_MICRON 3 1288 1289 /** Time codes are multiples of 8. **/ 1290 /*! NIFTI code for seconds. */ 1291 #define NIFTI_UNITS_SEC 8 1292 /*! NIFTI code for milliseconds. */ 1293 #define NIFTI_UNITS_MSEC 16 1294 /*! NIFTI code for microseconds. */ 1295 #define NIFTI_UNITS_USEC 24 1296 1297 /*** These units are for spectral data: ***/ 1298 /*! NIFTI code for Hertz. */ 1299 #define NIFTI_UNITS_HZ 32 1300 /*! NIFTI code for ppm. */ 1301 #define NIFTI_UNITS_PPM 40 1302 /*! NIFTI code for radians per second. */ 1303 #define NIFTI_UNITS_RADS 48 1304 /* @} */ 1305 1306 #undef XYZT_TO_SPACE 1307 #undef XYZT_TO_TIME 1308 #define XYZT_TO_SPACE(xyzt) ( (xyzt) & 0x07 ) 1309 #define XYZT_TO_TIME(xyzt) ( (xyzt) & 0x38 ) 1310 1311 #undef SPACE_TIME_TO_XYZT 1312 #define SPACE_TIME_TO_XYZT(ss,tt) ( (((char)(ss)) & 0x07) \ 1313 | (((char)(tt)) & 0x38) ) 1314 1315 /*---------------------------------------------------------------------------*/ 1316 /* MRI-SPECIFIC SPATIAL AND TEMPORAL INFORMATION: 1317 --------------------------------------------- 1318 A few fields are provided to store some extra information 1319 that is sometimes important when storing the image data 1320 from an FMRI time series experiment. (After processing such 1321 data into statistical images, these fields are not likely 1322 to be useful.) 1323 1324 { freq_dim } = These fields encode which spatial dimension (1,2, or 3) 1325 { phase_dim } = corresponds to which acquisition dimension for MRI data. 1326 { slice_dim } = 1327 Examples: 1328 Rectangular scan multi-slice EPI: 1329 freq_dim = 1 phase_dim = 2 slice_dim = 3 (or some permutation) 1330 Spiral scan multi-slice EPI: 1331 freq_dim = phase_dim = 0 slice_dim = 3 1332 since the concepts of frequency- and phase-encoding directions 1333 don't apply to spiral scan 1334 1335 slice_duration = If this is positive, AND if slice_dim is nonzero, 1336 indicates the amount of time used to acquire 1 slice. 1337 slice_duration*dim[slice_dim] can be less than pixdim[4] 1338 with a clustered acquisition method, for example. 1339 1340 slice_code = If this is nonzero, AND if slice_dim is nonzero, AND 1341 if slice_duration is positive, indicates the timing 1342 pattern of the slice acquisition. The following codes 1343 are defined: 1344 NIFTI_SLICE_SEQ_INC == sequential increasing 1345 NIFTI_SLICE_SEQ_DEC == sequential decreasing 1346 NIFTI_SLICE_ALT_INC == alternating increasing 1347 NIFTI_SLICE_ALT_DEC == alternating decreasing 1348 NIFTI_SLICE_ALT_INC2 == alternating increasing #2 1349 NIFTI_SLICE_ALT_DEC2 == alternating decreasing #2 1350 { slice_start } = Indicates the start and end of the slice acquisition 1351 { slice_end } = pattern, when slice_code is nonzero. These values 1352 are present to allow for the possible addition of 1353 "padded" slices at either end of the volume, which 1354 don't fit into the slice timing pattern. If there 1355 are no padding slices, then slice_start=0 and 1356 slice_end=dim[slice_dim]-1 are the correct values. 1357 For these values to be meaningful, slice_start must 1358 be non-negative and slice_end must be greater than 1359 slice_start. Otherwise, they should be ignored. 1360 1361 The following table indicates the slice timing pattern, relative to 1362 time=0 for the first slice acquired, for some sample cases. Here, 1363 dim[slice_dim]=7 (there are 7 slices, labeled 0..6), slice_duration=0.1, 1364 and slice_start=1, slice_end=5 (1 padded slice on each end). 1365 1366 slice 1367 index SEQ_INC SEQ_DEC ALT_INC ALT_DEC ALT_INC2 ALT_DEC2 1368 6 : n/a n/a n/a n/a n/a n/a n/a = not applicable 1369 5 : 0.4 0.0 0.2 0.0 0.4 0.2 (slice time offset 1370 4 : 0.3 0.1 0.4 0.3 0.1 0.0 doesn't apply to 1371 3 : 0.2 0.2 0.1 0.1 0.3 0.3 slices outside 1372 2 : 0.1 0.3 0.3 0.4 0.0 0.1 the range 1373 1 : 0.0 0.4 0.0 0.2 0.2 0.4 slice_start .. 1374 0 : n/a n/a n/a n/a n/a n/a slice_end) 1375 1376 The SEQ slice_codes are sequential ordering (uncommon but not unknown), 1377 either increasing in slice number or decreasing (INC or DEC), as 1378 illustrated above. 1379 1380 The ALT slice codes are alternating ordering. The 'standard' way for 1381 these to operate (without the '2' on the end) is for the slice timing 1382 to start at the edge of the slice_start .. slice_end group (at slice_start 1383 for INC and at slice_end for DEC). For the 'ALT_*2' slice_codes, the 1384 slice timing instead starts at the first slice in from the edge (at 1385 slice_start+1 for INC2 and at slice_end-1 for DEC2). This latter 1386 acquisition scheme is found on some Siemens scanners. 1387 1388 The fields freq_dim, phase_dim, slice_dim are all squished into the single 1389 byte field dim_info (2 bits each, since the values for each field are 1390 limited to the range 0..3). This unpleasantness is due to lack of space 1391 in the 348 byte allowance. 1392 1393 The macros DIM_INFO_TO_FREQ_DIM, DIM_INFO_TO_PHASE_DIM, and 1394 DIM_INFO_TO_SLICE_DIM can be used to extract these values from the 1395 dim_info byte. 1396 1397 The macro FPS_INTO_DIM_INFO can be used to put these 3 values 1398 into the dim_info byte. 1399 -----------------------------------------------------------------------------*/ 1400 1401 #undef DIM_INFO_TO_FREQ_DIM 1402 #undef DIM_INFO_TO_PHASE_DIM 1403 #undef DIM_INFO_TO_SLICE_DIM 1404 1405 #define DIM_INFO_TO_FREQ_DIM(di) ( ((di) ) & 0x03 ) 1406 #define DIM_INFO_TO_PHASE_DIM(di) ( ((di) >> 2) & 0x03 ) 1407 #define DIM_INFO_TO_SLICE_DIM(di) ( ((di) >> 4) & 0x03 ) 1408 1409 #undef FPS_INTO_DIM_INFO 1410 #define FPS_INTO_DIM_INFO(fd,pd,sd) ( ( ( ((char)(fd)) & 0x03) ) | \ 1411 ( ( ((char)(pd)) & 0x03) << 2 ) | \ 1412 ( ( ((char)(sd)) & 0x03) << 4 ) ) 1413 1414 /*! \defgroup NIFTI1_SLICE_ORDER 1415 \brief nifti1 slice order codes, describing the acquisition order 1416 of the slices 1417 @{ 1418 */ 1419 #define NIFTI_SLICE_UNKNOWN 0 1420 #define NIFTI_SLICE_SEQ_INC 1 1421 #define NIFTI_SLICE_SEQ_DEC 2 1422 #define NIFTI_SLICE_ALT_INC 3 1423 #define NIFTI_SLICE_ALT_DEC 4 1424 #define NIFTI_SLICE_ALT_INC2 5 /* 05 May 2005: RWCox */ 1425 #define NIFTI_SLICE_ALT_DEC2 6 /* 05 May 2005: RWCox */ 1426 /* @} */ 1427 1428 /*---------------------------------------------------------------------------*/ 1429 /* UNUSED FIELDS: 1430 ------------- 1431 Some of the ANALYZE 7.5 fields marked as ++UNUSED++ may need to be set 1432 to particular values for compatibility with other programs. The issue 1433 of interoperability of ANALYZE 7.5 files is a murky one -- not all 1434 programs require exactly the same set of fields. (Unobscuring this 1435 murkiness is a principal motivation behind NIFTI-1.) 1436 1437 Some of the fields that may need to be set for other (non-NIFTI aware) 1438 software to be happy are: 1439 1440 extents dbh.h says this should be 16384 1441 regular dbh.h says this should be the character 'r' 1442 glmin, } dbh.h says these values should be the min and max voxel 1443 glmax } values for the entire dataset 1444 1445 It is best to initialize ALL fields in the NIFTI-1 header to 0 1446 (e.g., with calloc()), then fill in what is needed. 1447 -----------------------------------------------------------------------------*/ 1448 1449 /*---------------------------------------------------------------------------*/ 1450 /* MISCELLANEOUS C MACROS 1451 -----------------------------------------------------------------------------*/ 1452 1453 /*.................*/ 1454 /*! Given a nifti_1_header struct, check if it has a good magic number. 1455 Returns NIFTI version number (1..9) if magic is good, 0 if it is not. */ 1456 1457 #define NIFTI_VERSION(h) \ 1458 ( ( (h).magic[0]=='n' && (h).magic[3]=='\0' && \ 1459 ( (h).magic[1]=='i' || (h).magic[1]=='+' ) && \ 1460 ( (h).magic[2]>='1' && (h).magic[2]<='9' ) ) \ 1461 ? (h).magic[2]-'0' : 0 ) 1462 1463 /*.................*/ 1464 /*! Check if a nifti_1_header struct says if the data is stored in the 1465 same file or in a separate file. Returns 1 if the data is in the same 1466 file as the header, 0 if it is not. */ 1467 1468 #define NIFTI_ONEFILE(h) ( (h).magic[1] == '+' ) 1469 1470 /*.................*/ 1471 /*! Check if a nifti_1_header struct needs to be byte swapped. 1472 Returns 1 if it needs to be swapped, 0 if it does not. */ 1473 1474 #define NIFTI_NEEDS_SWAP(h) ( (h).dim[0] < 0 || (h).dim[0] > 7 ) 1475 1476 /*.................*/ 1477 /*! Check if a nifti_1_header struct contains a 5th (vector) dimension. 1478 Returns size of 5th dimension if > 1, returns 0 otherwise. */ 1479 1480 #define NIFTI_5TH_DIM(h) ( ((h).dim[0]>4 && (h).dim[5]>1) ? (h).dim[5] : 0 ) 1481 1482 /*****************************************************************************/ 1483 1484 /*=================*/ 1485 #ifdef __cplusplus 1486 } 1487 #endif 1488 /*=================*/ 1489 1490 #endif /* _NIFTI_HEADER_ */ 1491