CiftiLib
A C++ library for CIFTI-2 and CIFTI-1 files
nifti1.h
1#ifndef _NIFTI_HEADER_
2#define _NIFTI_HEADER_
3
4/*LICENSE_START*/
5/*
6 * Copyright (c) 2014, Washington University School of Medicine
7 * All rights reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without modification,
10 * are permitted provided that the following conditions are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
28 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30/*
31 * NOTE: our version is somewhat modified, turning constant #defines into const int32_t, namespacing, removal of some other #defines, to try to coexist with the original header
32*/
33namespace cifti
34{
35
36/*****************************************************************************
37 ** This file defines the "NIFTI-1" header format. **
38 ** It is derived from 2 meetings at the NIH (31 Mar 2003 and **
39 ** 02 Sep 2003) of the Data Format Working Group (DFWG), **
40 ** chartered by the NIfTI (Neuroimaging Informatics Technology **
41 ** Initiative) at the National Institutes of Health (NIH). **
42 **--------------------------------------------------------------**
43 ** Neither the National Institutes of Health (NIH), the DFWG, **
44 ** nor any of the members or employees of these institutions **
45 ** imply any warranty of usefulness of this material for any **
46 ** purpose, and do not assume any liability for damages, **
47 ** incidental or otherwise, caused by any use of this document. **
48 ** If these conditions are not acceptable, do not use this! **
49 **--------------------------------------------------------------**
50 ** Author: Robert W Cox (NIMH, Bethesda) **
51 ** Advisors: John Ashburner (FIL, London), **
52 ** Stephen Smith (FMRIB, Oxford), **
53 ** Mark Jenkinson (FMRIB, Oxford) **
54******************************************************************************/
55
56/*---------------------------------------------------------------------------*/
57/* Note that the ANALYZE 7.5 file header (dbh.h) is
58 (c) Copyright 1986-1995
59 Biomedical Imaging Resource
60 Mayo Foundation
61 Incorporation of components of dbh.h are by permission of the
62 Mayo Foundation.
63
64 Changes from the ANALYZE 7.5 file header in this file are released to the
65 public domain, including the functional comments and any amusing asides.
66-----------------------------------------------------------------------------*/
67
68/*---------------------------------------------------------------------------*/
136/*---------------------------------------------------------------------------*/
137/* HEADER STRUCT DECLARATION:
138 -------------------------
139 In the comments below for each field, only NIFTI-1 specific requirements
140 or changes from the ANALYZE 7.5 format are described. For convenience,
141 the 348 byte header is described as a single struct, rather than as the
142 ANALYZE 7.5 group of 3 substructs.
143
144 Further comments about the interpretation of various elements of this
145 header are after the data type definition itself. Fields that are
146 marked as ++UNUSED++ have no particular interpretation in this standard.
147 (Also see the UNUSED FIELDS comment section, far below.)
148
149 The presumption below is that the various C types have particular sizes:
150 sizeof(int) = sizeof(float) = 4 ; sizeof(short) = 2
151-----------------------------------------------------------------------------*/
152
153//hopefully cross-platform solution to byte padding added by some compilers
154#pragma pack(push)
155#pragma pack(1)
156
162/*************************/ /************************/
163struct nifti_1_header { /* NIFTI-1 usage */ /* ANALYZE 7.5 field(s) */
164 /*************************/ /************************/
165
166 /*--- was header_key substruct ---*/
167 int sizeof_hdr; /* int sizeof_hdr; */ /* 0 */
168 char data_type[10]; /* char data_type[10]; */ /* 4 */
169 char db_name[18]; /* char db_name[18]; */ /* 14 */
170 int extents; /* int extents; */ /* 32 */
171 short session_error; /* short session_error; */ /* 36 */
172 char regular; /* char regular; */ /* 38 */
173 char dim_info; /* char hkey_un0; */ /* 39 */
174
175 /*--- was image_dimension substruct ---*/
176 short dim[8]; /* short dim[8]; */ /* 40 */
177 float intent_p1 ; /* short unused8; */ /* 56 */
178 /* short unused9; */
179 float intent_p2 ; /* short unused10; */ /* 60 */
180 /* short unused11; */
181 float intent_p3 ; /* short unused12; */ /* 64 */
182 /* short unused13; */
183 short intent_code ; /* short unused14; */ /* 68 */
184 short datatype; /* short datatype; */ /* 70 */
185 short bitpix; /* short bitpix; */ /* 72 */
186 short slice_start; /* short dim_un0; */ /* 74 */
187 float pixdim[8]; /* float pixdim[8]; */ /* 76 */
188 float vox_offset; /* float vox_offset; */ /* 108 */
189 float scl_slope ; /* float funused1; */ /* 112 */
190 float scl_inter ; /* float funused2; */ /* 116 */
191 short slice_end; /* float funused3; */ /* 120 */
192 char slice_code ; /* 122 */
193 char xyzt_units ; /* 123 */
194 float cal_max; /* float cal_max; */ /* 124 */
195 float cal_min; /* float cal_min; */ /* 128 */
196 float slice_duration; /* float compressed; */ /* 132 */
197 float toffset; /* float verified; */ /* 136 */
198 int glmax; /* int glmax; */ /* 140 */
199 int glmin; /* int glmin; */ /* 144 */
200
201 /*--- was data_history substruct ---*/
202 char descrip[80]; /* char descrip[80]; */ /* 148 */
203 char aux_file[24]; /* char aux_file[24]; */ /* 228 */
204
205 short qform_code ; /*-- all ANALYZE 7.5 ---*/ /* 252 */
206 short sform_code ; /* fields below here */ /* 254 */
207 /* are replaced */
208 float quatern_b ; /* 256 */
209 float quatern_c ; /* 260 */
210 float quatern_d ; /* 264 */
211 float qoffset_x ; /* 268 */
212 float qoffset_y ; /* 272 */
213 float qoffset_z ; /* 276 */
214
215 float srow_x[4] ; /* 280 */
216 float srow_y[4] ; /* 296 */
217 float srow_z[4] ; /* 312 */
218
219 char intent_name[16]; /* 328 */
220
221 char magic[4] ; /* 344 */
222
223} ; /**** 348 bytes total ****/
224
225typedef struct nifti_1_header nifti_1_header ;
226
227/*---------------------------------------------------------------------------*/
228/* HEADER EXTENSIONS:
229 -----------------
230 After the end of the 348 byte header (e.g., after the magic field),
231 the next 4 bytes are a char array field named "extension". By default,
232 all 4 bytes of this array should be set to zero. In a .nii file, these
233 4 bytes will always be present, since the earliest start point for
234 the image data is byte #352. In a separate .hdr file, these bytes may
235 or may not be present. If not present (i.e., if the length of the .hdr
236 file is 348 bytes), then a NIfTI-1 compliant program should use the
237 default value of extension={0,0,0,0}. The first byte (extension[0])
238 is the only value of this array that is specified at present. The other
239 3 bytes are reserved for future use.
240
241 If extension[0] is nonzero, it indicates that extended header information
242 is present in the bytes following the extension array. In a .nii file,
243 this extended header data is before the image data (and vox_offset
244 must be set correctly to allow for this). In a .hdr file, this extended
245 data follows extension and proceeds (potentially) to the end of the file.
246
247 The format of extended header data is weakly specified. Each extension
248 must be an integer multiple of 16 bytes long. The first 8 bytes of each
249 extension comprise 2 integers:
250 int esize , ecode ;
251 These values may need to be byte-swapped, as indicated by dim[0] for
252 the rest of the header.
253 * esize is the number of bytes that form the extended header data
254 + esize must be a positive integral multiple of 16
255 + this length includes the 8 bytes of esize and ecode themselves
256 * ecode is a non-negative integer that indicates the format of the
257 extended header data that follows
258 + different ecode values are assigned to different developer groups
259 + at present, the "registered" values for code are
260 = 0 = unknown private format (not recommended!)
261 = 2 = DICOM format (i.e., attribute tags and values)
262 = 4 = AFNI group (i.e., ASCII XML-ish elements)
263 In the interests of interoperability (a primary rationale for NIfTI),
264 groups developing software that uses this extension mechanism are
265 encouraged to document and publicize the format of their extensions.
266 To this end, the NIfTI DFWG will assign even numbered codes upon request
267 to groups submitting at least rudimentary documentation for the format
268 of their extension; at present, the contact is mailto:rwcox@nih.gov.
269 The assigned codes and documentation will be posted on the NIfTI
270 website. All odd values of ecode (and 0) will remain unassigned;
271 at least, until the even ones are used up, when we get to 2,147,483,646.
272
273 Note that the other contents of the extended header data section are
274 totally unspecified by the NIfTI-1 standard. In particular, if binary
275 data is stored in such a section, its byte order is not necessarily
276 the same as that given by examining dim[0]; it is incumbent on the
277 programs dealing with such data to determine the byte order of binary
278 extended header data.
279
280 Multiple extended header sections are allowed, each starting with an
281 esize,ecode value pair. The first esize value, as described above,
282 is at bytes #352-355 in the .hdr or .nii file (files start at byte #0).
283 If this value is positive, then the second (esize2) will be found
284 starting at byte #352+esize1 , the third (esize3) at byte #352+esize1+esize2,
285 et cetera. Of course, in a .nii file, the value of vox_offset must
286 be compatible with these extensions. If a malformed file indicates
287 that an extended header data section would run past vox_offset, then
288 the entire extended header section should be ignored. In a .hdr file,
289 if an extended header data section would run past the end-of-file,
290 that extended header data should also be ignored.
291
292 With the above scheme, a program can successively examine the esize
293 and ecode values, and skip over each extended header section if the
294 program doesn't know how to interpret the data within. Of course, any
295 program can simply ignore all extended header sections simply by jumping
296 straight to the image data using vox_offset.
297-----------------------------------------------------------------------------*/
298
306struct nifti1_extender { char extension[4] ; } ;
307typedef struct nifti1_extender nifti1_extender ;
308
313 int esize ;
314 int ecode ;
315 char * edata ;
316} ;
317typedef struct nifti1_extension nifti1_extension ;
318
319//and restore packing behavior
320#pragma pack(pop)
321
322/*---------------------------------------------------------------------------*/
323/* DATA DIMENSIONALITY (as in ANALYZE 7.5):
324 ---------------------------------------
325 dim[0] = number of dimensions;
326 - if dim[0] is outside range 1..7, then the header information
327 needs to be byte swapped appropriately
328 - ANALYZE supports dim[0] up to 7, but NIFTI-1 reserves
329 dimensions 1,2,3 for space (x,y,z), 4 for time (t), and
330 5,6,7 for anything else needed.
331
332 dim[i] = length of dimension #i, for i=1..dim[0] (must be positive)
333 - also see the discussion of intent_code, far below
334
335 pixdim[i] = voxel width along dimension #i, i=1..dim[0] (positive)
336 - cf. ORIENTATION section below for use of pixdim[0]
337 - the units of pixdim can be specified with the xyzt_units
338 field (also described far below).
339
340 Number of bits per voxel value is in bitpix, which MUST correspond with
341 the datatype field. The total number of bytes in the image data is
342 dim[1] * ... * dim[dim[0]] * bitpix / 8
343
344 In NIFTI-1 files, dimensions 1,2,3 are for space, dimension 4 is for time,
345 and dimension 5 is for storing multiple values at each spatiotemporal
346 voxel. Some examples:
347 - A typical whole-brain FMRI experiment's time series:
348 - dim[0] = 4
349 - dim[1] = 64 pixdim[1] = 3.75 xyzt_units = NIFTI_UNITS_MM
350 - dim[2] = 64 pixdim[2] = 3.75 | NIFTI_UNITS_SEC
351 - dim[3] = 20 pixdim[3] = 5.0
352 - dim[4] = 120 pixdim[4] = 2.0
353 - A typical T1-weighted anatomical volume:
354 - dim[0] = 3
355 - dim[1] = 256 pixdim[1] = 1.0 xyzt_units = NIFTI_UNITS_MM
356 - dim[2] = 256 pixdim[2] = 1.0
357 - dim[3] = 128 pixdim[3] = 1.1
358 - A single slice EPI time series:
359 - dim[0] = 4
360 - dim[1] = 64 pixdim[1] = 3.75 xyzt_units = NIFTI_UNITS_MM
361 - dim[2] = 64 pixdim[2] = 3.75 | NIFTI_UNITS_SEC
362 - dim[3] = 1 pixdim[3] = 5.0
363 - dim[4] = 1200 pixdim[4] = 0.2
364 - A 3-vector stored at each point in a 3D volume:
365 - dim[0] = 5
366 - dim[1] = 256 pixdim[1] = 1.0 xyzt_units = NIFTI_UNITS_MM
367 - dim[2] = 256 pixdim[2] = 1.0
368 - dim[3] = 128 pixdim[3] = 1.1
369 - dim[4] = 1 pixdim[4] = 0.0
370 - dim[5] = 3 intent_code = NIFTI_INTENT_VECTOR
371 - A single time series with a 3x3 matrix at each point:
372 - dim[0] = 5
373 - dim[1] = 1 xyzt_units = NIFTI_UNITS_SEC
374 - dim[2] = 1
375 - dim[3] = 1
376 - dim[4] = 1200 pixdim[4] = 0.2
377 - dim[5] = 9 intent_code = NIFTI_INTENT_GENMATRIX
378 - intent_p1 = intent_p2 = 3.0 (indicates matrix dimensions)
379-----------------------------------------------------------------------------*/
380
381/*---------------------------------------------------------------------------*/
382/* DATA STORAGE:
383 ------------
384 If the magic field is "n+1", then the voxel data is stored in the
385 same file as the header. In this case, the voxel data starts at offset
386 (int)vox_offset into the header file. Thus, vox_offset=352.0 means that
387 the data starts immediately after the NIFTI-1 header. If vox_offset is
388 greater than 352, the NIFTI-1 format does not say much about the
389 contents of the dataset file between the end of the header and the
390 start of the data.
391
392 FILES:
393 -----
394 If the magic field is "ni1", then the voxel data is stored in the
395 associated ".img" file, starting at offset 0 (i.e., vox_offset is not
396 used in this case, and should be set to 0.0).
397
398 When storing NIFTI-1 datasets in pairs of files, it is customary to name
399 the files in the pattern "name.hdr" and "name.img", as in ANALYZE 7.5.
400 When storing in a single file ("n+1"), the file name should be in
401 the form "name.nii" (the ".nft" and ".nif" suffixes are already taken;
402 cf. http://www.icdatamaster.com/n.html ).
403
404 BYTE ORDERING:
405 -------------
406 The byte order of the data arrays is presumed to be the same as the byte
407 order of the header (which is determined by examining dim[0]).
408
409 Floating point types are presumed to be stored in IEEE-754 format.
410-----------------------------------------------------------------------------*/
411
412/*---------------------------------------------------------------------------*/
413/* DETAILS ABOUT vox_offset:
414 ------------------------
415 In a .nii file, the vox_offset field value is interpreted as the start
416 location of the image data bytes in that file. In a .hdr/.img file pair,
417 the vox_offset field value is the start location of the image data
418 bytes in the .img file.
419 * If vox_offset is less than 352 in a .nii file, it is equivalent
420 to 352 (i.e., image data never starts before byte #352 in a .nii file).
421 * The default value for vox_offset in a .nii file is 352.
422 * In a .hdr file, the default value for vox_offset is 0.
423 * vox_offset should be an integer multiple of 16; otherwise, some
424 programs may not work properly (e.g., SPM). This is to allow
425 memory-mapped input to be properly byte-aligned.
426 Note that since vox_offset is an IEEE-754 32 bit float (for compatibility
427 with the ANALYZE-7.5 format), it effectively has a 24 bit mantissa. All
428 integers from 0 to 2^24 can be represented exactly in this format, but not
429 all larger integers are exactly storable as IEEE-754 32 bit floats. However,
430 unless you plan to have vox_offset be potentially larger than 16 MB, this
431 should not be an issue. (Actually, any integral multiple of 16 up to 2^27
432 can be represented exactly in this format, which allows for up to 128 MB
433 of random information before the image data. If that isn't enough, then
434 perhaps this format isn't right for you.)
435
436 In a .img file (i.e., image data stored separately from the NIfTI-1
437 header), data bytes between #0 and #vox_offset-1 (inclusive) are completely
438 undefined and unregulated by the NIfTI-1 standard. One potential use of
439 having vox_offset > 0 in the .hdr/.img file pair storage method is to make
440 the .img file be a copy of (or link to) a pre-existing image file in some
441 other format, such as DICOM; then vox_offset would be set to the offset of
442 the image data in this file. (It may not be possible to follow the
443 "multiple-of-16 rule" with an arbitrary external file; using the NIfTI-1
444 format in such a case may lead to a file that is incompatible with software
445 that relies on vox_offset being a multiple of 16.)
446
447 In a .nii file, data bytes between #348 and #vox_offset-1 (inclusive) may
448 be used to store user-defined extra information; similarly, in a .hdr file,
449 any data bytes after byte #347 are available for user-defined extra
450 information. The (very weak) regulation of this extra header data is
451 described elsewhere.
452-----------------------------------------------------------------------------*/
453
454/*---------------------------------------------------------------------------*/
455/* DATA SCALING:
456 ------------
457 If the scl_slope field is nonzero, then each voxel value in the dataset
458 should be scaled as
459 y = scl_slope * x + scl_inter
460 where x = voxel value stored
461 y = "true" voxel value
462 Normally, we would expect this scaling to be used to store "true" floating
463 values in a smaller integer datatype, but that is not required. That is,
464 it is legal to use scaling even if the datatype is a float type (crazy,
465 perhaps, but legal).
466 - However, the scaling is to be ignored if datatype is DT_RGB24.
467 - If datatype is a complex type, then the scaling is to be
468 applied to both the real and imaginary parts.
469
470 The cal_min and cal_max fields (if nonzero) are used for mapping (possibly
471 scaled) dataset values to display colors:
472 - Minimum display intensity (black) corresponds to dataset value cal_min.
473 - Maximum display intensity (white) corresponds to dataset value cal_max.
474 - Dataset values below cal_min should display as black also, and values
475 above cal_max as white.
476 - Colors "black" and "white", of course, may refer to any scalar display
477 scheme (e.g., a color lookup table specified via aux_file).
478 - cal_min and cal_max only make sense when applied to scalar-valued
479 datasets (i.e., dim[0] < 5 or dim[5] = 1).
480-----------------------------------------------------------------------------*/
481
482/*---------------------------------------------------------------------------*/
483/* TYPE OF DATA (acceptable values for datatype field):
484 ---------------------------------------------------
485 Values of datatype smaller than 256 are ANALYZE 7.5 compatible.
486 Larger values are NIFTI-1 additions. These are all multiples of 256, so
487 that no bits below position 8 are set in datatype. But there is no need
488 to use only powers-of-2, as the original ANALYZE 7.5 datatype codes do.
489
490 The additional codes are intended to include a complete list of basic
491 scalar types, including signed and unsigned integers from 8 to 64 bits,
492 floats from 32 to 128 bits, and complex (float pairs) from 64 to 256 bits.
493
494 Note that most programs will support only a few of these datatypes!
495 A NIFTI-1 program should fail gracefully (e.g., print a warning message)
496 when it encounters a dataset with a type it doesn't like.
497-----------------------------------------------------------------------------*/
498
499#undef DT_UNKNOWN /* defined in dirent.h on some Unix systems */
500#include<stdint.h>
505/*--- the original ANALYZE 7.5 type codes ---*/
506const int32_t DT_NONE =0;
507const int32_t DT_UNKNOWN =0; /* what it says, dude */
508const int32_t DT_BINARY =1; /* binary (1 bit/voxel) */
509const int32_t DT_UNSIGNED_CHAR =2; /* unsigned char (8 bits/voxel) */
510const int32_t DT_SIGNED_SHORT =4; /* signed short (16 bits/voxel) */
511const int32_t DT_SIGNED_INT =8; /* signed int (32 bits/voxel) */
512const int32_t DT_FLOAT =16; /* float (32 bits/voxel) */
513const int32_t DT_COMPLEX =32; /* complex (64 bits/voxel) */
514const int32_t DT_DOUBLE =64; /* double (64 bits/voxel) */
515const int32_t DT_RGB =128; /* RGB triple (24 bits/voxel) */
516const int32_t DT_ALL =255; /* not very useful (?) */
517
518/*----- another set of names for the same ---*/
519const int32_t DT_UINT8 =2;
520const int32_t DT_INT16 =4;
521const int32_t DT_INT32 =8;
522const int32_t DT_FLOAT32 =16;
523const int32_t DT_COMPLEX64 =32;
524const int32_t DT_FLOAT64 =64;
525const int32_t DT_RGB24 =128;
526
527/*------------------- new codes for NIFTI ---*/
528const int32_t DT_INT8 =256; /* signed char (8 bits) */
529const int32_t DT_UINT16 =512; /* unsigned short (16 bits) */
530const int32_t DT_UINT32 =768; /* unsigned int (32 bits) */
531const int32_t DT_INT64 =1024; /* long long (64 bits) */
532const int32_t DT_UINT64 =1280; /* unsigned long long (64 bits) */
533const int32_t DT_FLOAT128 =1536; /* long double (128 bits) */
534const int32_t DT_COMPLEX128 =1792; /* double pair (128 bits) */
535const int32_t DT_COMPLEX256 =2048; /* long double pair (256 bits) */
536/* @} */
537
538
539/*------- aliases for all the above codes ---*/
540
546const int32_t NIFTI_TYPE_UINT8 =2;
548const int32_t NIFTI_TYPE_INT16 =4;
550const int32_t NIFTI_TYPE_INT32 =8;
552const int32_t NIFTI_TYPE_FLOAT32 =16;
554const int32_t NIFTI_TYPE_COMPLEX64 =32;
556const int32_t NIFTI_TYPE_FLOAT64 =64;
558const int32_t NIFTI_TYPE_RGB24 =128;
560const int32_t NIFTI_TYPE_INT8 =256;
562const int32_t NIFTI_TYPE_UINT16 =512;
564const int32_t NIFTI_TYPE_UINT32 =768;
566const int32_t NIFTI_TYPE_INT64 =1024;
568const int32_t NIFTI_TYPE_UINT64 =1280;
570const int32_t NIFTI_TYPE_FLOAT128 =1536;
572const int32_t NIFTI_TYPE_COMPLEX128 =1792;
574const int32_t NIFTI_TYPE_COMPLEX256 =2048;
575/* @} */
576
577/*-------- sample typedefs for complicated types ---*/
578#if 0
579typedef struct { float r,i; } complex_float ;
580typedef struct { double r,i; } complex_double ;
581typedef struct { long double r,i; } complex_longdouble ;
582typedef struct { unsigned char r,g,b; } rgb_byte ;
583#endif
584
585/*---------------------------------------------------------------------------*/
586/* INTERPRETATION OF VOXEL DATA:
587 ----------------------------
588 The intent_code field can be used to indicate that the voxel data has
589 some particular meaning. In particular, a large number of codes is
590 given to indicate that the the voxel data should be interpreted as
591 being drawn from a given probability distribution.
592
593 VECTOR-VALUED DATASETS:
594 ----------------------
595 The 5th dimension of the dataset, if present (i.e., dim[0]=5 and
596 dim[5] > 1), contains multiple values (e.g., a vector) to be stored
597 at each spatiotemporal location. For example, the header values
598 - dim[0] = 5
599 - dim[1] = 64
600 - dim[2] = 64
601 - dim[3] = 20
602 - dim[4] = 1 (indicates no time axis)
603 - dim[5] = 3
604 - datatype = DT_FLOAT
605 - intent_code = NIFTI_INTENT_VECTOR
606 mean that this dataset should be interpreted as a 3D volume (64x64x20),
607 with a 3-vector of floats defined at each point in the 3D grid.
608
609 A program reading a dataset with a 5th dimension may want to reformat
610 the image data to store each voxels' set of values together in a struct
611 or array. This programming detail, however, is beyond the scope of the
612 NIFTI-1 file specification! Uses of dimensions 6 and 7 are also not
613 specified here.
614
615 STATISTICAL PARAMETRIC DATASETS (i.e., SPMs):
616 --------------------------------------------
617 Values of intent_code from NIFTI_FIRST_STATCODE to NIFTI_LAST_STATCODE
618 (inclusive) indicate that the numbers in the dataset should be interpreted
619 as being drawn from a given distribution. Most such distributions have
620 auxiliary parameters (e.g., NIFTI_INTENT_TTEST has 1 DOF parameter).
621
622 If the dataset DOES NOT have a 5th dimension, then the auxiliary parameters
623 are the same for each voxel, and are given in header fields intent_p1,
624 intent_p2, and intent_p3.
625
626 If the dataset DOES have a 5th dimension, then the auxiliary parameters
627 are different for each voxel. For example, the header values
628 - dim[0] = 5
629 - dim[1] = 128
630 - dim[2] = 128
631 - dim[3] = 1 (indicates a single slice)
632 - dim[4] = 1 (indicates no time axis)
633 - dim[5] = 2
634 - datatype = DT_FLOAT
635 - intent_code = NIFTI_INTENT_TTEST
636 mean that this is a 2D dataset (128x128) of t-statistics, with the
637 t-statistic being in the first "plane" of data and the degrees-of-freedom
638 parameter being in the second "plane" of data.
639
640 If the dataset 5th dimension is used to store the voxel-wise statistical
641 parameters, then dim[5] must be 1 plus the number of parameters required
642 by that distribution (e.g., intent_code=NIFTI_INTENT_TTEST implies dim[5]
643 must be 2, as in the example just above).
644
645 Note: intent_code values 2..10 are compatible with AFNI 1.5x (which is
646 why there is no code with value=1, which is obsolescent in AFNI).
647
648 OTHER INTENTIONS:
649 ----------------
650 The purpose of the intent_* fields is to help interpret the values
651 stored in the dataset. Some non-statistical values for intent_code
652 and conventions are provided for storing other complex data types.
653
654 The intent_name field provides space for a 15 character (plus 0 byte)
655 'name' string for the type of data stored. Examples:
656 - intent_code = NIFTI_INTENT_ESTIMATE; intent_name = "T1";
657 could be used to signify that the voxel values are estimates of the
658 NMR parameter T1.
659 - intent_code = NIFTI_INTENT_TTEST; intent_name = "House";
660 could be used to signify that the voxel values are t-statistics
661 for the significance of 'activation' response to a House stimulus.
662 - intent_code = NIFTI_INTENT_DISPVECT; intent_name = "ToMNI152";
663 could be used to signify that the voxel values are a displacement
664 vector that transforms each voxel (x,y,z) location to the
665 corresponding location in the MNI152 standard brain.
666 - intent_code = NIFTI_INTENT_SYMMATRIX; intent_name = "DTI";
667 could be used to signify that the voxel values comprise a diffusion
668 tensor image.
669
670 If no data name is implied or needed, intent_name[0] should be set to 0.
671-----------------------------------------------------------------------------*/
672
675const int32_t NIFTI_INTENT_NONE =0;
676
677/*-------- These codes are for probability distributions ---------------*/
678/* Most distributions have a number of parameters,
679 below denoted by p1, p2, and p3, and stored in
680 - intent_p1, intent_p2, intent_p3 if dataset doesn't have 5th dimension
681 - image data array if dataset does have 5th dimension
682
683 Functions to compute with many of the distributions below can be found
684 in the CDF library from U Texas.
685
686 Formulas for and discussions of these distributions can be found in the
687 following books:
688
689 [U] Univariate Discrete Distributions,
690 NL Johnson, S Kotz, AW Kemp.
691
692 [C1] Continuous Univariate Distributions, vol. 1,
693 NL Johnson, S Kotz, N Balakrishnan.
694
695 [C2] Continuous Univariate Distributions, vol. 2,
696 NL Johnson, S Kotz, N Balakrishnan. */
697/*----------------------------------------------------------------------*/
698
707const int32_t NIFTI_INTENT_CORREL =2;
708
711const int32_t NIFTI_INTENT_TTEST =3;
712
716const int32_t NIFTI_INTENT_FTEST =4;
717
720const int32_t NIFTI_INTENT_ZSCORE =5;
721
725const int32_t NIFTI_INTENT_CHISQ =6;
726
730const int32_t NIFTI_INTENT_BETA =7;
731
736const int32_t NIFTI_INTENT_BINOM =8;
737
742const int32_t NIFTI_INTENT_GAMMA =9;
743
747const int32_t NIFTI_INTENT_POISSON =10;
748
752const int32_t NIFTI_INTENT_NORMAL =11;
753
758const int32_t NIFTI_INTENT_FTEST_NONC=12;
759
763const int32_t NIFTI_INTENT_CHISQ_NONC=13;
764
769const int32_t NIFTI_INTENT_LOGISTIC =14;
770
775const int32_t NIFTI_INTENT_LAPLACE =15;
776
779const int32_t NIFTI_INTENT_UNIFORM =16;
780
784const int32_t NIFTI_INTENT_TTEST_NONC=17;
785
791const int32_t NIFTI_INTENT_WEIBULL =18;
792
799const int32_t NIFTI_INTENT_CHI =19;
800
806const int32_t NIFTI_INTENT_INVGAUSS =20;
807
812const int32_t NIFTI_INTENT_EXTVAL =21;
813
816const int32_t NIFTI_INTENT_PVAL =22;
817
824const int32_t NIFTI_INTENT_LOGPVAL =23;
825
831const int32_t NIFTI_INTENT_LOG10PVAL =24;
832
835const int32_t NIFTI_FIRST_STATCODE =2;
836
839const int32_t NIFTI_LAST_STATCODE =24;
840
841/*---------- these values for intent_code aren't for statistics ----------*/
842
847const int32_t NIFTI_INTENT_ESTIMATE =1001;
848
853const int32_t NIFTI_INTENT_LABEL =1002;
854
858const int32_t NIFTI_INTENT_NEURONAME=1003;
859
872const int32_t NIFTI_INTENT_GENMATRIX=1004;
873
885const int32_t NIFTI_INTENT_SYMMATRIX=1005;
886
894const int32_t NIFTI_INTENT_DISPVECT =1006; /* specifically for displacements */
895const int32_t NIFTI_INTENT_VECTOR =1007; /* for any other type of vector */
896
908const int32_t NIFTI_INTENT_POINTSET =1008;
909
921const int32_t NIFTI_INTENT_TRIANGLE =1009;
922
930const int32_t NIFTI_INTENT_QUATERNION=1010;
931
935const int32_t NIFTI_INTENT_DIMLESS =1011;
936/* @} */
937
938/*---------------------------------------------------------------------------*/
939/* 3D IMAGE (VOLUME) ORIENTATION AND LOCATION IN SPACE:
940 ---------------------------------------------------
941 There are 3 different methods by which continuous coordinates can
942 attached to voxels. The discussion below emphasizes 3D volumes, and
943 the continuous coordinates are referred to as (x,y,z). The voxel
944 index coordinates (i.e., the array indexes) are referred to as (i,j,k),
945 with valid ranges:
946 i = 0 .. dim[1]-1
947 j = 0 .. dim[2]-1 (if dim[0] >= 2)
948 k = 0 .. dim[3]-1 (if dim[0] >= 3)
949 The (x,y,z) coordinates refer to the CENTER of a voxel. In methods
950 2 and 3, the (x,y,z) axes refer to a subject-based coordinate system,
951 with
952 +x = Right +y = Anterior +z = Superior.
953 This is a right-handed coordinate system. However, the exact direction
954 these axes point with respect to the subject depends on qform_code
955 (Method 2) and sform_code (Method 3).
956
957 N.B.: The i index varies most rapidly, j index next, k index slowest.
958 Thus, voxel (i,j,k) is stored starting at location
959 (i + j*dim[1] + k*dim[1]*dim[2]) * (bitpix/8)
960 into the dataset array.
961
962 N.B.: The ANALYZE 7.5 coordinate system is
963 +x = Left +y = Anterior +z = Superior
964 which is a left-handed coordinate system. This backwardness is
965 too difficult to tolerate, so this NIFTI-1 standard specifies the
966 coordinate order which is most common in functional neuroimaging.
967
968 N.B.: The 3 methods below all give the locations of the voxel centers
969 in the (x,y,z) coordinate system. In many cases, programs will wish
970 to display image data on some other grid. In such a case, the program
971 will need to convert its desired (x,y,z) values into (i,j,k) values
972 in order to extract (or interpolate) the image data. This operation
973 would be done with the inverse transformation to those described below.
974
975 N.B.: Method 2 uses a factor 'qfac' which is either -1 or 1; qfac is
976 stored in the otherwise unused pixdim[0]. If pixdim[0]=0.0 (which
977 should not occur), we take qfac=1. Of course, pixdim[0] is only used
978 when reading a NIFTI-1 header, not when reading an ANALYZE 7.5 header.
979
980 N.B.: The units of (x,y,z) can be specified using the xyzt_units field.
981
982 METHOD 1 (the "old" way, used only when qform_code = 0):
983 -------------------------------------------------------
984 The coordinate mapping from (i,j,k) to (x,y,z) is the ANALYZE
985 7.5 way. This is a simple scaling relationship:
986
987 x = pixdim[1] * i
988 y = pixdim[2] * j
989 z = pixdim[3] * k
990
991 No particular spatial orientation is attached to these (x,y,z)
992 coordinates. (NIFTI-1 does not have the ANALYZE 7.5 orient field,
993 which is not general and is often not set properly.) This method
994 is not recommended, and is present mainly for compatibility with
995 ANALYZE 7.5 files.
996
997 METHOD 2 (used when qform_code > 0, which should be the "normal" case):
998 ---------------------------------------------------------------------
999 The (x,y,z) coordinates are given by the pixdim[] scales, a rotation
1000 matrix, and a shift. This method is intended to represent
1001 "scanner-anatomical" coordinates, which are often embedded in the
1002 image header (e.g., DICOM fields (0020,0032), (0020,0037), (0028,0030),
1003 and (0018,0050)), and represent the nominal orientation and location of
1004 the data. This method can also be used to represent "aligned"
1005 coordinates, which would typically result from some post-acquisition
1006 alignment of the volume to a standard orientation (e.g., the same
1007 subject on another day, or a rigid rotation to true anatomical
1008 orientation from the tilted position of the subject in the scanner).
1009 The formula for (x,y,z) in terms of header parameters and (i,j,k) is:
1010
1011 [ x ] [ R11 R12 R13 ] [ pixdim[1] * i ] [ qoffset_x ]
1012 [ y ] = [ R21 R22 R23 ] [ pixdim[2] * j ] + [ qoffset_y ]
1013 [ z ] [ R31 R32 R33 ] [ qfac * pixdim[3] * k ] [ qoffset_z ]
1014
1015 The qoffset_* shifts are in the NIFTI-1 header. Note that the center
1016 of the (i,j,k)=(0,0,0) voxel (first value in the dataset array) is
1017 just (x,y,z)=(qoffset_x,qoffset_y,qoffset_z).
1018
1019 The rotation matrix R is calculated from the quatern_* parameters.
1020 This calculation is described below.
1021
1022 The scaling factor qfac is either 1 or -1. The rotation matrix R
1023 defined by the quaternion parameters is "proper" (has determinant 1).
1024 This may not fit the needs of the data; for example, if the image
1025 grid is
1026 i increases from Left-to-Right
1027 j increases from Anterior-to-Posterior
1028 k increases from Inferior-to-Superior
1029 Then (i,j,k) is a left-handed triple. In this example, if qfac=1,
1030 the R matrix would have to be
1031
1032 [ 1 0 0 ]
1033 [ 0 -1 0 ] which is "improper" (determinant = -1).
1034 [ 0 0 1 ]
1035
1036 If we set qfac=-1, then the R matrix would be
1037
1038 [ 1 0 0 ]
1039 [ 0 -1 0 ] which is proper.
1040 [ 0 0 -1 ]
1041
1042 This R matrix is represented by quaternion [a,b,c,d] = [0,1,0,0]
1043 (which encodes a 180 degree rotation about the x-axis).
1044
1045 METHOD 3 (used when sform_code > 0):
1046 -----------------------------------
1047 The (x,y,z) coordinates are given by a general affine transformation
1048 of the (i,j,k) indexes:
1049
1050 x = srow_x[0] * i + srow_x[1] * j + srow_x[2] * k + srow_x[3]
1051 y = srow_y[0] * i + srow_y[1] * j + srow_y[2] * k + srow_y[3]
1052 z = srow_z[0] * i + srow_z[1] * j + srow_z[2] * k + srow_z[3]
1053
1054 The srow_* vectors are in the NIFTI_1 header. Note that no use is
1055 made of pixdim[] in this method.
1056
1057 WHY 3 METHODS?
1058 --------------
1059 Method 1 is provided only for backwards compatibility. The intention
1060 is that Method 2 (qform_code > 0) represents the nominal voxel locations
1061 as reported by the scanner, or as rotated to some fiducial orientation and
1062 location. Method 3, if present (sform_code > 0), is to be used to give
1063 the location of the voxels in some standard space. The sform_code
1064 indicates which standard space is present. Both methods 2 and 3 can be
1065 present, and be useful in different contexts (method 2 for displaying the
1066 data on its original grid; method 3 for displaying it on a standard grid).
1067
1068 In this scheme, a dataset would originally be set up so that the
1069 Method 2 coordinates represent what the scanner reported. Later,
1070 a registration to some standard space can be computed and inserted
1071 in the header. Image display software can use either transform,
1072 depending on its purposes and needs.
1073
1074 In Method 2, the origin of coordinates would generally be whatever
1075 the scanner origin is; for example, in MRI, (0,0,0) is the center
1076 of the gradient coil.
1077
1078 In Method 3, the origin of coordinates would depend on the value
1079 of sform_code; for example, for the Talairach coordinate system,
1080 (0,0,0) corresponds to the Anterior Commissure.
1081
1082 QUATERNION REPRESENTATION OF ROTATION MATRIX (METHOD 2)
1083 -------------------------------------------------------
1084 The orientation of the (x,y,z) axes relative to the (i,j,k) axes
1085 in 3D space is specified using a unit quaternion [a,b,c,d], where
1086 a*a+b*b+c*c+d*d=1. The (b,c,d) values are all that is needed, since
1087 we require that a = sqrt(1.0-(b*b+c*c+d*d)) be nonnegative. The (b,c,d)
1088 values are stored in the (quatern_b,quatern_c,quatern_d) fields.
1089
1090 The quaternion representation is chosen for its compactness in
1091 representing rotations. The (proper) 3x3 rotation matrix that
1092 corresponds to [a,b,c,d] is
1093
1094 [ a*a+b*b-c*c-d*d 2*b*c-2*a*d 2*b*d+2*a*c ]
1095 R = [ 2*b*c+2*a*d a*a+c*c-b*b-d*d 2*c*d-2*a*b ]
1096 [ 2*b*d-2*a*c 2*c*d+2*a*b a*a+d*d-c*c-b*b ]
1097
1098 [ R11 R12 R13 ]
1099 = [ R21 R22 R23 ]
1100 [ R31 R32 R33 ]
1101
1102 If (p,q,r) is a unit 3-vector, then rotation of angle h about that
1103 direction is represented by the quaternion
1104
1105 [a,b,c,d] = [cos(h/2), p*sin(h/2), q*sin(h/2), r*sin(h/2)].
1106
1107 Requiring a >= 0 is equivalent to requiring -Pi <= h <= Pi. (Note that
1108 [-a,-b,-c,-d] represents the same rotation as [a,b,c,d]; there are 2
1109 quaternions that can be used to represent a given rotation matrix R.)
1110 To rotate a 3-vector (x,y,z) using quaternions, we compute the
1111 quaternion product
1112
1113 [0,x',y',z'] = [a,b,c,d] * [0,x,y,z] * [a,-b,-c,-d]
1114
1115 which is equivalent to the matrix-vector multiply
1116
1117 [ x' ] [ x ]
1118 [ y' ] = R [ y ] (equivalence depends on a*a+b*b+c*c+d*d=1)
1119 [ z' ] [ z ]
1120
1121 Multiplication of 2 quaternions is defined by the following:
1122
1123 [a,b,c,d] = a*1 + b*I + c*J + d*K
1124 where
1125 I*I = J*J = K*K = -1 (I,J,K are square roots of -1)
1126 I*J = K J*K = I K*I = J
1127 J*I = -K K*J = -I I*K = -J (not commutative!)
1128 For example
1129 [a,b,0,0] * [0,0,0,1] = [0,0,-b,a]
1130 since this expands to
1131 (a+b*I)*(K) = (a*K+b*I*K) = (a*K-b*J).
1132
1133 The above formula shows how to go from quaternion (b,c,d) to
1134 rotation matrix and direction cosines. Conversely, given R,
1135 we can compute the fields for the NIFTI-1 header by
1136
1137 a = 0.5 * sqrt(1+R11+R22+R33) (not stored)
1138 b = 0.25 * (R32-R23) / a => quatern_b
1139 c = 0.25 * (R13-R31) / a => quatern_c
1140 d = 0.25 * (R21-R12) / a => quatern_d
1141
1142 If a=0 (a 180 degree rotation), alternative formulas are needed.
1143 See the nifti1_io.c function mat44_to_quatern() for an implementation
1144 of the various cases in converting R to [a,b,c,d].
1145
1146 Note that R-transpose (= R-inverse) would lead to the quaternion
1147 [a,-b,-c,-d].
1148
1149 The choice to specify the qoffset_x (etc.) values in the final
1150 coordinate system is partly to make it easy to convert DICOM images to
1151 this format. The DICOM attribute "Image Position (Patient)" (0020,0032)
1152 stores the (Xd,Yd,Zd) coordinates of the center of the first voxel.
1153 Here, (Xd,Yd,Zd) refer to DICOM coordinates, and Xd=-x, Yd=-y, Zd=z,
1154 where (x,y,z) refers to the NIFTI coordinate system discussed above.
1155 (i.e., DICOM +Xd is Left, +Yd is Posterior, +Zd is Superior,
1156 whereas +x is Right, +y is Anterior , +z is Superior. )
1157 Thus, if the (0020,0032) DICOM attribute is extracted into (px,py,pz), then
1158 qoffset_x = -px qoffset_y = -py qoffset_z = pz
1159 is a reasonable setting when qform_code=NIFTI_XFORM_SCANNER_ANAT.
1160
1161 That is, DICOM's coordinate system is 180 degrees rotated about the z-axis
1162 from the neuroscience/NIFTI coordinate system. To transform between DICOM
1163 and NIFTI, you just have to negate the x- and y-coordinates.
1164
1165 The DICOM attribute (0020,0037) "Image Orientation (Patient)" gives the
1166 orientation of the x- and y-axes of the image data in terms of 2 3-vectors.
1167 The first vector is a unit vector along the x-axis, and the second is
1168 along the y-axis. If the (0020,0037) attribute is extracted into the
1169 value (xa,xb,xc,ya,yb,yc), then the first two columns of the R matrix
1170 would be
1171 [ -xa -ya ]
1172 [ -xb -yb ]
1173 [ xc yc ]
1174 The negations are because DICOM's x- and y-axes are reversed relative
1175 to NIFTI's. The third column of the R matrix gives the direction of
1176 displacement (relative to the subject) along the slice-wise direction.
1177 This orientation is not encoded in the DICOM standard in a simple way;
1178 DICOM is mostly concerned with 2D images. The third column of R will be
1179 either the cross-product of the first 2 columns or its negative. It is
1180 possible to infer the sign of the 3rd column by examining the coordinates
1181 in DICOM attribute (0020,0032) "Image Position (Patient)" for successive
1182 slices. However, this method occasionally fails for reasons that I
1183 (RW Cox) do not understand.
1184-----------------------------------------------------------------------------*/
1185
1186/* [qs]form_code value: */ /* x,y,z coordinate system refers to: */
1187/*-----------------------*/ /*---------------------------------------*/
1188
1195const int32_t NIFTI_XFORM_UNKNOWN =0;
1196
1200
1205
1209const int32_t NIFTI_XFORM_TALAIRACH =3;
1210
1213const int32_t NIFTI_XFORM_MNI_152 =4;
1214/* @} */
1215
1216/*---------------------------------------------------------------------------*/
1217/* UNITS OF SPATIAL AND TEMPORAL DIMENSIONS:
1218 ----------------------------------------
1219 The codes below can be used in xyzt_units to indicate the units of pixdim.
1220 As noted earlier, dimensions 1,2,3 are for x,y,z; dimension 4 is for
1221 time (t).
1222 - If dim[4]=1 or dim[0] < 4, there is no time axis.
1223 - A single time series (no space) would be specified with
1224 - dim[0] = 4 (for scalar data) or dim[0] = 5 (for vector data)
1225 - dim[1] = dim[2] = dim[3] = 1
1226 - dim[4] = number of time points
1227 - pixdim[4] = time step
1228 - xyzt_units indicates units of pixdim[4]
1229 - dim[5] = number of values stored at each time point
1230
1231 Bits 0..2 of xyzt_units specify the units of pixdim[1..3]
1232 (e.g., spatial units are values 1..7).
1233 Bits 3..5 of xyzt_units specify the units of pixdim[4]
1234 (e.g., temporal units are multiples of 8).
1235
1236 This compression of 2 distinct concepts into 1 byte is due to the
1237 limited space available in the 348 byte ANALYZE 7.5 header. The
1238 macros XYZT_TO_SPACE and XYZT_TO_TIME can be used to mask off the
1239 undesired bits from the xyzt_units fields, leaving "pure" space
1240 and time codes. Inversely, the macro SPACE_TIME_TO_XYZT can be
1241 used to assemble a space code (0,1,2,...,7) with a time code
1242 (0,8,16,32,...,56) into the combined value for xyzt_units.
1243
1244 Note that codes are provided to indicate the "time" axis units are
1245 actually frequency in Hertz (_HZ), in part-per-million (_PPM)
1246 or in radians-per-second (_RADS).
1247
1248 The toffset field can be used to indicate a nonzero start point for
1249 the time axis. That is, time point #m is at t=toffset+m*pixdim[4]
1250 for m=0..dim[4]-1.
1251-----------------------------------------------------------------------------*/
1252
1259const int32_t NIFTI_UNITS_UNKNOWN=0;
1260
1263const int32_t NIFTI_UNITS_METER =1;
1265const int32_t NIFTI_UNITS_MM =2;
1267const int32_t NIFTI_UNITS_MICRON =3;
1268
1271const int32_t NIFTI_UNITS_SEC =8;
1273const int32_t NIFTI_UNITS_MSEC =16;
1275const int32_t NIFTI_UNITS_USEC =24;
1276
1277/*** These units are for spectral data: ***/
1279const int32_t NIFTI_UNITS_HZ =32;
1281const int32_t NIFTI_UNITS_PPM =40;
1283const int32_t NIFTI_UNITS_RADS =48;
1284/* @} */
1285
1286#undef XYZT_TO_SPACE
1287#undef XYZT_TO_TIME
1288#define XYZT_TO_SPACE(xyzt) ( (xyzt) & 0x07 )
1289#define XYZT_TO_TIME(xyzt) ( (xyzt) & 0x38 )
1290
1291#undef SPACE_TIME_TO_XYZT
1292#define SPACE_TIME_TO_XYZT(ss,tt) ( (((char)(ss)) & 0x07) \
1293 | (((char)(tt)) & 0x38) )
1294
1295/*---------------------------------------------------------------------------*/
1296/* MRI-SPECIFIC SPATIAL AND TEMPORAL INFORMATION:
1297 ---------------------------------------------
1298 A few fields are provided to store some extra information
1299 that is sometimes important when storing the image data
1300 from an FMRI time series experiment. (After processing such
1301 data into statistical images, these fields are not likely
1302 to be useful.)
1303
1304 { freq_dim } = These fields encode which spatial dimension (1,2, or 3)
1305 { phase_dim } = corresponds to which acquisition dimension for MRI data.
1306 { slice_dim } =
1307 Examples:
1308 Rectangular scan multi-slice EPI:
1309 freq_dim = 1 phase_dim = 2 slice_dim = 3 (or some permutation)
1310 Spiral scan multi-slice EPI:
1311 freq_dim = phase_dim = 0 slice_dim = 3
1312 since the concepts of frequency- and phase-encoding directions
1313 don't apply to spiral scan
1314
1315 slice_duration = If this is positive, AND if slice_dim is nonzero,
1316 indicates the amount of time used to acquire 1 slice.
1317 slice_duration*dim[slice_dim] can be less than pixdim[4]
1318 with a clustered acquisition method, for example.
1319
1320 slice_code = If this is nonzero, AND if slice_dim is nonzero, AND
1321 if slice_duration is positive, indicates the timing
1322 pattern of the slice acquisition. The following codes
1323 are defined:
1324 NIFTI_SLICE_SEQ_INC == sequential increasing
1325 NIFTI_SLICE_SEQ_DEC == sequential decreasing
1326 NIFTI_SLICE_ALT_INC == alternating increasing
1327 NIFTI_SLICE_ALT_DEC == alternating decreasing
1328 NIFTI_SLICE_ALT_INC2 == alternating increasing #2
1329 NIFTI_SLICE_ALT_DEC2 == alternating decreasing #2
1330 { slice_start } = Indicates the start and end of the slice acquisition
1331 { slice_end } = pattern, when slice_code is nonzero. These values
1332 are present to allow for the possible addition of
1333 "padded" slices at either end of the volume, which
1334 don't fit into the slice timing pattern. If there
1335 are no padding slices, then slice_start=0 and
1336 slice_end=dim[slice_dim]-1 are the correct values.
1337 For these values to be meaningful, slice_start must
1338 be non-negative and slice_end must be greater than
1339 slice_start. Otherwise, they should be ignored.
1340
1341 The following table indicates the slice timing pattern, relative to
1342 time=0 for the first slice acquired, for some sample cases. Here,
1343 dim[slice_dim]=7 (there are 7 slices, labeled 0..6), slice_duration=0.1,
1344 and slice_start=1, slice_end=5 (1 padded slice on each end).
1345
1346 slice
1347 index SEQ_INC SEQ_DEC ALT_INC ALT_DEC ALT_INC2 ALT_DEC2
1348 6 : n/a n/a n/a n/a n/a n/a n/a = not applicable
1349 5 : 0.4 0.0 0.2 0.0 0.4 0.2 (slice time offset
1350 4 : 0.3 0.1 0.4 0.3 0.1 0.0 doesn't apply to
1351 3 : 0.2 0.2 0.1 0.1 0.3 0.3 slices outside
1352 2 : 0.1 0.3 0.3 0.4 0.0 0.1 the range
1353 1 : 0.0 0.4 0.0 0.2 0.2 0.4 slice_start ..
1354 0 : n/a n/a n/a n/a n/a n/a slice_end)
1355
1356 The SEQ slice_codes are sequential ordering (uncommon but not unknown),
1357 either increasing in slice number or decreasing (INC or DEC), as
1358 illustrated above.
1359
1360 The ALT slice codes are alternating ordering. The 'standard' way for
1361 these to operate (without the '2' on the end) is for the slice timing
1362 to start at the edge of the slice_start .. slice_end group (at slice_start
1363 for INC and at slice_end for DEC). For the 'ALT_*2' slice_codes, the
1364 slice timing instead starts at the first slice in from the edge (at
1365 slice_start+1 for INC2 and at slice_end-1 for DEC2). This latter
1366 acquisition scheme is found on some Siemens scanners.
1367
1368 The fields freq_dim, phase_dim, slice_dim are all squished into the single
1369 byte field dim_info (2 bits each, since the values for each field are
1370 limited to the range 0..3). This unpleasantness is due to lack of space
1371 in the 348 byte allowance.
1372
1373 The macros DIM_INFO_TO_FREQ_DIM, DIM_INFO_TO_PHASE_DIM, and
1374 DIM_INFO_TO_SLICE_DIM can be used to extract these values from the
1375 dim_info byte.
1376
1377 The macro FPS_INTO_DIM_INFO can be used to put these 3 values
1378 into the dim_info byte.
1379-----------------------------------------------------------------------------*/
1380
1381#undef DIM_INFO_TO_FREQ_DIM
1382#undef DIM_INFO_TO_PHASE_DIM
1383#undef DIM_INFO_TO_SLICE_DIM
1384
1385#define DIM_INFO_TO_FREQ_DIM(di) ( ((di) ) & 0x03 )
1386#define DIM_INFO_TO_PHASE_DIM(di) ( ((di) >> 2) & 0x03 )
1387#define DIM_INFO_TO_SLICE_DIM(di) ( ((di) >> 4) & 0x03 )
1388
1389#undef FPS_INTO_DIM_INFO
1390#define FPS_INTO_DIM_INFO(fd,pd,sd) ( ( ( ((char)(fd)) & 0x03) ) | \
1391 ( ( ((char)(pd)) & 0x03) << 2 ) | \
1392 ( ( ((char)(sd)) & 0x03) << 4 ) )
1393
1399const int32_t NIFTI_SLICE_UNKNOWN =0;
1400const int32_t NIFTI_SLICE_SEQ_INC =1;
1401const int32_t NIFTI_SLICE_SEQ_DEC =2;
1402const int32_t NIFTI_SLICE_ALT_INC =3;
1403const int32_t NIFTI_SLICE_ALT_DEC =4;
1404const int32_t NIFTI_SLICE_ALT_INC2 =5; /* 05 May 2005: RWCox */
1405const int32_t NIFTI_SLICE_ALT_DEC2 =6; /* 05 May 2005: RWCox */
1406/* @} */
1407
1408/*---------------------------------------------------------------------------*/
1409/* UNUSED FIELDS:
1410 -------------
1411 Some of the ANALYZE 7.5 fields marked as ++UNUSED++ may need to be set
1412 to particular values for compatibility with other programs. The issue
1413 of interoperability of ANALYZE 7.5 files is a murky one -- not all
1414 programs require exactly the same set of fields. (Unobscuring this
1415 murkiness is a principal motivation behind NIFTI-1.)
1416
1417 Some of the fields that may need to be set for other (non-NIFTI aware)
1418 software to be happy are:
1419
1420 extents dbh.h says this should be 16384
1421 regular dbh.h says this should be the character 'r'
1422 glmin, } dbh.h says these values should be the min and max voxel
1423 glmax } values for the entire dataset
1424
1425 It is best to initialize ALL fields in the NIFTI-1 header to 0
1426 (e.g., with calloc()), then fill in what is needed.
1427-----------------------------------------------------------------------------*/
1428
1429/*---------------------------------------------------------------------------*/
1430/* MISCELLANEOUS C MACROS
1431-----------------------------------------------------------------------------*/
1432
1433/*.................*/
1437/*#define NIFTI_VERSION(h) \
1438 ( ( (h).magic[0]=='n' && (h).magic[3]=='\0' && \
1439 ( (h).magic[1]=='i' || (h).magic[1]=='+' ) && \
1440 ( (h).magic[2]>='1' && (h).magic[2]<='9' ) ) \
1441 ? (h).magic[2]-'0' : 0 )
1442
1443//*/
1444
1445/*.................*/
1450//#define NIFTI_ONEFILE(h) ( (h).magic[1] == '+' )
1451
1452/*.................*/
1456//#define NIFTI_NEEDS_SWAP(h) ( (h).dim[0] < 0 || (h).dim[0] > 7 )
1457
1458/*.................*/
1462//#define NIFTI_5TH_DIM(h) ( ((h).dim[0]>4 && (h).dim[5]>1) ? (h).dim[5] : 0 )
1463
1464/*****************************************************************************/
1465
1466}//namespace
1467
1468#endif /* _NIFTI_HEADER_ */
const int32_t NIFTI_TYPE_UINT64
Definition nifti1.h:568
const int32_t NIFTI_INTENT_NONE
Definition nifti1.h:675
const int32_t NIFTI_TYPE_COMPLEX64
Definition nifti1.h:554
const int32_t NIFTI_TYPE_FLOAT64
Definition nifti1.h:556
const int32_t NIFTI_TYPE_INT8
Definition nifti1.h:560
const int32_t NIFTI_TYPE_UINT8
Definition nifti1.h:546
const int32_t NIFTI_TYPE_FLOAT32
Definition nifti1.h:552
const int32_t NIFTI_TYPE_RGB24
Definition nifti1.h:558
const int32_t NIFTI_TYPE_INT64
Definition nifti1.h:566
const int32_t NIFTI_TYPE_INT32
Definition nifti1.h:550
const int32_t NIFTI_TYPE_INT16
Definition nifti1.h:548
const int32_t NIFTI_TYPE_UINT16
Definition nifti1.h:562
const int32_t NIFTI_TYPE_COMPLEX128
Definition nifti1.h:572
const int32_t NIFTI_TYPE_FLOAT128
Definition nifti1.h:570
const int32_t NIFTI_TYPE_COMPLEX256
Definition nifti1.h:574
const int32_t NIFTI_TYPE_UINT32
Definition nifti1.h:564
const int32_t NIFTI_LAST_STATCODE
Definition nifti1.h:839
const int32_t NIFTI_INTENT_GENMATRIX
Definition nifti1.h:872
const int32_t NIFTI_INTENT_QUATERNION
Definition nifti1.h:930
const int32_t NIFTI_INTENT_FTEST
Definition nifti1.h:716
const int32_t NIFTI_INTENT_CHISQ_NONC
Definition nifti1.h:763
const int32_t NIFTI_INTENT_ZSCORE
Definition nifti1.h:720
const int32_t NIFTI_INTENT_NORMAL
Definition nifti1.h:752
const int32_t NIFTI_INTENT_TRIANGLE
Definition nifti1.h:921
const int32_t NIFTI_INTENT_CHI
Definition nifti1.h:799
const int32_t NIFTI_INTENT_BINOM
Definition nifti1.h:736
const int32_t NIFTI_INTENT_DISPVECT
Definition nifti1.h:894
const int32_t NIFTI_INTENT_TTEST
Definition nifti1.h:711
const int32_t NIFTI_FIRST_STATCODE
Definition nifti1.h:835
const int32_t NIFTI_INTENT_CHISQ
Definition nifti1.h:725
const int32_t NIFTI_INTENT_LOGISTIC
Definition nifti1.h:769
const int32_t NIFTI_INTENT_PVAL
Definition nifti1.h:816
const int32_t NIFTI_INTENT_POINTSET
Definition nifti1.h:908
const int32_t NIFTI_INTENT_UNIFORM
Definition nifti1.h:779
const int32_t NIFTI_INTENT_NEURONAME
Definition nifti1.h:858
const int32_t NIFTI_INTENT_TTEST_NONC
Definition nifti1.h:784
const int32_t NIFTI_INTENT_LAPLACE
Definition nifti1.h:775
const int32_t NIFTI_INTENT_FTEST_NONC
Definition nifti1.h:758
const int32_t NIFTI_INTENT_GAMMA
Definition nifti1.h:742
const int32_t NIFTI_INTENT_EXTVAL
Definition nifti1.h:812
const int32_t NIFTI_INTENT_WEIBULL
Definition nifti1.h:791
const int32_t NIFTI_INTENT_INVGAUSS
Definition nifti1.h:806
const int32_t NIFTI_INTENT_ESTIMATE
Definition nifti1.h:847
const int32_t NIFTI_INTENT_LOGPVAL
Definition nifti1.h:824
const int32_t NIFTI_INTENT_LABEL
Definition nifti1.h:853
const int32_t NIFTI_INTENT_POISSON
Definition nifti1.h:747
const int32_t NIFTI_INTENT_DIMLESS
Definition nifti1.h:935
const int32_t NIFTI_INTENT_SYMMATRIX
Definition nifti1.h:885
const int32_t NIFTI_INTENT_LOG10PVAL
Definition nifti1.h:831
const int32_t NIFTI_INTENT_BETA
Definition nifti1.h:730
float cal_max
Definition nifti1.h:194
short slice_end
Definition nifti1.h:191
char slice_code
Definition nifti1.h:192
int sizeof_hdr
Definition nifti1.h:167
char dim_info
Definition nifti1.h:173
char db_name[18]
Definition nifti1.h:169
int ecode
Definition nifti1.h:314
float srow_y[4]
Definition nifti1.h:216
float pixdim[8]
Definition nifti1.h:187
float intent_p2
Definition nifti1.h:179
short intent_code
Definition nifti1.h:183
float quatern_d
Definition nifti1.h:210
char magic[4]
Definition nifti1.h:221
short qform_code
Definition nifti1.h:205
float qoffset_x
Definition nifti1.h:211
int esize
Definition nifti1.h:313
float cal_min
Definition nifti1.h:195
char data_type[10]
Definition nifti1.h:168
int glmin
Definition nifti1.h:199
int extents
Definition nifti1.h:170
float quatern_c
Definition nifti1.h:209
char intent_name[16]
Definition nifti1.h:219
float intent_p1
Definition nifti1.h:177
float toffset
Definition nifti1.h:197
float quatern_b
Definition nifti1.h:208
short slice_start
Definition nifti1.h:186
char * edata
Definition nifti1.h:315
float srow_z[4]
Definition nifti1.h:217
float srow_x[4]
Definition nifti1.h:215
float intent_p3
Definition nifti1.h:181
short datatype
Definition nifti1.h:184
float qoffset_y
Definition nifti1.h:212
char xyzt_units
Definition nifti1.h:193
short bitpix
Definition nifti1.h:185
char regular
Definition nifti1.h:172
int glmax
Definition nifti1.h:198
float qoffset_z
Definition nifti1.h:213
float vox_offset
Definition nifti1.h:188
float scl_slope
Definition nifti1.h:189
short dim[8]
Definition nifti1.h:176
short sform_code
Definition nifti1.h:206
float slice_duration
Definition nifti1.h:196
float scl_inter
Definition nifti1.h:190
char descrip[80]
Definition nifti1.h:202
char aux_file[24]
Definition nifti1.h:203
short session_error
Definition nifti1.h:171
const int32_t NIFTI_UNITS_MSEC
Definition nifti1.h:1273
const int32_t NIFTI_UNITS_RADS
Definition nifti1.h:1283
const int32_t NIFTI_UNITS_UNKNOWN
Definition nifti1.h:1259
const int32_t NIFTI_UNITS_METER
Definition nifti1.h:1263
const int32_t NIFTI_UNITS_PPM
Definition nifti1.h:1281
const int32_t NIFTI_UNITS_MM
Definition nifti1.h:1265
const int32_t NIFTI_UNITS_HZ
Definition nifti1.h:1279
const int32_t NIFTI_UNITS_SEC
Definition nifti1.h:1271
const int32_t NIFTI_UNITS_MICRON
Definition nifti1.h:1267
const int32_t NIFTI_UNITS_USEC
Definition nifti1.h:1275
const int32_t NIFTI_XFORM_UNKNOWN
Definition nifti1.h:1195
const int32_t NIFTI_XFORM_MNI_152
Definition nifti1.h:1213
const int32_t NIFTI_XFORM_TALAIRACH
Definition nifti1.h:1209
const int32_t NIFTI_XFORM_SCANNER_ANAT
Definition nifti1.h:1199
const int32_t NIFTI_XFORM_ALIGNED_ANAT
Definition nifti1.h:1204
namespace for all CiftiLib functionality
Definition CiftiBrainModelsMap.h:42
This structure represents a 4-byte string that should follow the binary nifti_1_header data in a NIFT...
Definition nifti1.h:306
Data structure defining the fields of a header extension.
Definition nifti1.h:312
Data structure defining the fields in the nifti1 header. This binary header should be found at the be...
Definition nifti1.h:163