1 /** \file nifti1_io.h 2 \brief Data structures for using nifti1_io API. 3 - Written by Bob Cox, SSCC NIMH 4 - Revisions by Rick Reynolds, SSCC NIMH 5 */ 6 #ifndef _NIFTI_IO_HEADER_ 7 #define _NIFTI_IO_HEADER_ 8 9 #include <stdio.h> 10 #include <stdlib.h> 11 #include <string.h> 12 #include <math.h> 13 #include <ctype.h> 14 15 #ifndef DONT_INCLUDE_ANALYZE_STRUCT 16 #define DONT_INCLUDE_ANALYZE_STRUCT /*** not needed herein ***/ 17 #endif 18 #include "nifti1.h" /*** NIFTI-1 header specification ***/ 19 20 #include "znzlib.h" 21 22 /*=================*/ 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 /*=================*/ 27 28 /*****===================================================================*****/ 29 /***** File nifti1_io.h == Declarations for nifti1_io.c *****/ 30 /*****...................................................................*****/ 31 /***** This code is released to the public domain. *****/ 32 /*****...................................................................*****/ 33 /***** Author: Robert W Cox, SSCC/DIRP/NIMH/NIH/DHHS/USA/EARTH *****/ 34 /***** Date: August 2003 *****/ 35 /*****...................................................................*****/ 36 /***** Neither the National Institutes of Health (NIH), nor any of its *****/ 37 /***** employees imply any warranty of usefulness of this software for *****/ 38 /***** any purpose, and do not assume any liability for damages, *****/ 39 /***** incidental or otherwise, caused by any use of this document. *****/ 40 /*****===================================================================*****/ 41 42 /* 43 Modified by: Mark Jenkinson (FMRIB Centre, University of Oxford, UK) 44 Date: July/August 2004 45 46 Mainly adding low-level IO and changing things to allow gzipped files 47 to be read and written 48 Full backwards compatability should have been maintained 49 50 Modified by: Rick Reynolds (SSCC/DIRP/NIMH, National Institutes of Health) 51 Date: December 2004 52 53 Modified and added many routines for I/O. 54 */ 55 56 /********************** Some sample data structures **************************/ 57 58 typedef struct { /** 4x4 matrix struct **/ 59 float m[4][4] ; 60 } mat44 ; 61 62 typedef struct { /** 3x3 matrix struct **/ 63 float m[3][3] ; 64 } mat33 ; 65 66 /*...........................................................................*/ 67 68 /*! \struct nifti_image 69 \brief High level data structure for open nifti datasets in the 70 nifti1_io API. Note that this structure is not part of the 71 nifti1 format definition; it is used to implement one API 72 for reading/writing formats in the nifti1 format. 73 */ 74 typedef struct { /*!< Image storage struct **/ 75 76 int ndim ; /*!< last dimension greater than 1 (1..7) */ 77 int nx ; /*!< dimensions of grid array */ 78 int ny ; /*!< dimensions of grid array */ 79 int nz ; /*!< dimensions of grid array */ 80 int nt ; /*!< dimensions of grid array */ 81 int nu ; /*!< dimensions of grid array */ 82 int nv ; /*!< dimensions of grid array */ 83 int nw ; /*!< dimensions of grid array */ 84 int dim[8] ; /*!< dim[0]=ndim, dim[1]=nx, etc. */ 85 int nvox ; /*!< number of voxels = nx*ny*nz*...*nw */ 86 int nbyper ; /*!< bytes per voxel, matches datatype */ 87 int datatype ; /*!< type of data in voxels: DT_* code */ 88 89 float dx ; /*!< grid spacings */ 90 float dy ; /*!< grid spacings */ 91 float dz ; /*!< grid spacings */ 92 float dt ; /*!< grid spacings */ 93 float du ; /*!< grid spacings */ 94 float dv ; /*!< grid spacings */ 95 float dw ; /*!< grid spacings */ 96 float pixdim[8] ; /*!< pixdim[1]=dx, etc. */ 97 98 float scl_slope ; /*!< scaling parameter - slope */ 99 float scl_inter ; /*!< scaling parameter - intercept */ 100 101 float cal_min ; /*!< calibration parameter, minimum */ 102 float cal_max ; /*!< calibration parameter, maximum */ 103 104 int qform_code ; /*!< codes for (x,y,z) space meaning */ 105 int sform_code ; /*!< codes for (x,y,z) space meaning */ 106 107 int freq_dim ; /*!< indexes (1,2,3, or 0) for MRI */ 108 int phase_dim ; /*!< directions in dim[]/pixdim[] */ 109 int slice_dim ; /*!< directions in dim[]/pixdim[] */ 110 111 int slice_code ; /*!< code for slice timing pattern */ 112 int slice_start ; /*!< index for start of slices */ 113 int slice_end ; /*!< index for end of slices */ 114 float slice_duration ; /*!< time between individual slices */ 115 116 /*! quaternion transform parameters 117 [when writing a dataset, these are used for qform, NOT qto_xyz] */ 118 float quatern_b , quatern_c , quatern_d , 119 qoffset_x , qoffset_y , qoffset_z , 120 qfac ; 121 122 mat44 qto_xyz ; /*!< qform: transform (i,j,k) to (x,y,z) */ 123 mat44 qto_ijk ; /*!< qform: transform (x,y,z) to (i,j,k) */ 124 125 mat44 sto_xyz ; /*!< sform: transform (i,j,k) to (x,y,z) */ 126 mat44 sto_ijk ; /*!< sform: transform (x,y,z) to (i,j,k) */ 127 128 float toffset ; /*!< time coordinate offset */ 129 130 int xyz_units ; /*!< dx,dy,dz units: NIFTI_UNITS_* code */ 131 int time_units ; /*!< dt units: NIFTI_UNITS_* code */ 132 133 int nifti_type ; /*!< 0==ANALYZE, 1==NIFTI-1 (1 file), 134 2==NIFTI-1 (2 files), 135 3==NIFTI-ASCII (1 file) */ 136 int intent_code ; /*!< statistic type (or something) */ 137 float intent_p1 ; /*!< intent parameters */ 138 float intent_p2 ; /*!< intent parameters */ 139 float intent_p3 ; /*!< intent parameters */ 140 char intent_name[16] ; /*!< optional description of intent data */ 141 142 char descrip[80] ; /*!< optional text to describe dataset */ 143 char aux_file[24] ; /*!< auxiliary filename */ 144 145 char *fname ; /*!< header filename (.hdr or .nii) */ 146 char *iname ; /*!< image filename (.img or .nii) */ 147 int iname_offset ; /*!< offset into iname where data starts */ 148 int swapsize ; /*!< swap unit in image data (might be 0) */ 149 int byteorder ; /*!< byte order on disk (MSB_ or LSB_FIRST) */ 150 void *data ; /*!< pointer to data: nbyper*nvox bytes */ 151 152 int num_ext ; /*!< number of extensions in ext_list */ 153 nifti1_extension * ext_list ; /*!< array of extension structs (with data) */ 154 155 } nifti_image ; 156 157 158 159 /* struct for return from nifti_image_read_bricks() */ 160 typedef struct { 161 int nbricks; /* the number of allocated pointers in 'bricks' */ 162 int bsize; /* the length of each data block, in bytes */ 163 void ** bricks; /* array of pointers to data blocks */ 164 } nifti_brick_list; 165 166 167 /*****************************************************************************/ 168 /*--------------- Prototypes of functions defined in this file --------------*/ 169 170 char *nifti_datatype_string ( int dt ) ; 171 char *nifti_units_string ( int uu ) ; 172 char *nifti_intent_string ( int ii ) ; 173 char *nifti_xform_string ( int xx ) ; 174 char *nifti_slice_string ( int ss ) ; 175 char *nifti_orientation_string( int ii ) ; 176 177 int nifti_is_inttype( int dt ) ; 178 179 mat44 nifti_mat44_inverse( mat44 R ) ; 180 181 mat33 nifti_mat33_inverse( mat33 R ) ; 182 mat33 nifti_mat33_polar ( mat33 A ) ; 183 float nifti_mat33_rownorm( mat33 A ) ; 184 float nifti_mat33_colnorm( mat33 A ) ; 185 float nifti_mat33_determ ( mat33 R ) ; 186 mat33 nifti_mat33_mul ( mat33 A , mat33 B ) ; 187 188 void nifti_swap_2bytes ( int n , void *ar ) ; 189 void nifti_swap_4bytes ( int n , void *ar ) ; 190 void nifti_swap_8bytes ( int n , void *ar ) ; 191 void nifti_swap_16bytes( int n , void *ar ) ; 192 void nifti_swap_Nbytes ( int n , int siz , void *ar ) ; 193 194 void swap_nifti_header ( struct nifti_1_header *h , int is_nifti ) ; 195 int nifti_get_filesize( const char *pathname ) ; 196 197 /* main read/write routines */ 198 199 nifti_image *nifti_image_read_bricks(const char *hname , int nbricks, 200 const int *blist, nifti_brick_list * NBL); 201 int nifti_image_load_bricks(nifti_image *nim , int nbricks, 202 const int *blist, nifti_brick_list * NBL); 203 void nifti_free_NBL( nifti_brick_list * NBL ); 204 205 nifti_image *nifti_image_read ( const char *hname , int read_data ) ; 206 int nifti_image_load ( nifti_image *nim ) ; 207 void nifti_image_unload ( nifti_image *nim ) ; 208 void nifti_image_free ( nifti_image *nim ) ; 209 210 int nifti_read_collapsed_image( nifti_image * nim, const int dims [8], 211 void ** data ); 212 213 void nifti_image_write ( nifti_image * nim ) ; 214 void nifti_image_write_bricks(nifti_image * nim, 215 const nifti_brick_list * NBL); 216 void nifti_image_infodump( const nifti_image * nim ) ; 217 218 void nifti_disp_lib_hist( void ) ; /* to display library history */ 219 void nifti_disp_lib_version( void ) ; /* to display library version */ 220 int nifti_disp_matrix_orient( const char * mesg, mat44 mat ); 221 222 char * nifti_image_to_ascii ( const nifti_image * nim ) ; 223 nifti_image *nifti_image_from_ascii( const char * str, int * bytes_read ) ; 224 225 size_t nifti_get_volsize(const nifti_image *nim) ; 226 227 /* basic file operations */ 228 int nifti_set_filenames(nifti_image * nim, const char * prefix, int check, 229 int set_byte_order); 230 char * nifti_makehdrname (const char * prefix, int nifti_type, int check, 231 int comp); 232 char * nifti_makeimgname (const char * prefix, int nifti_type, int check, 233 int comp); 234 int is_nifti_file (const char *hname); 235 char * nifti_find_file_extension(const char * name); 236 int nifti_is_complete_filename(const char* fname); 237 int nifti_validfilename(const char* fname); 238 239 int disp_nifti_1_header(const char * info, const nifti_1_header * hp ) ; 240 void nifti_set_debug_level( int level ) ; 241 void nifti_set_skip_blank_ext( int skip ) ; 242 243 int valid_nifti_brick_list(nifti_image * nim , int nbricks, 244 const int * blist, int disp_error); 245 246 /* znzFile operations */ 247 znzFile nifti_image_open(const char * hname, char * opts, nifti_image ** nim); 248 znzFile nifti_image_write_hdr_img(nifti_image *nim, int write_data, 249 const char* opts); 250 znzFile nifti_image_write_hdr_img2( nifti_image *nim , int write_opts , 251 const char* opts, znzFile imgfile, const nifti_brick_list * NBL); 252 size_t nifti_read_buffer(znzFile fp, void* datatptr, size_t ntot, 253 nifti_image *nim); 254 int nifti_write_all_data(znzFile fp, nifti_image * nim, 255 const nifti_brick_list * NBL); 256 size_t nifti_write_buffer(znzFile fp, const void * buffer, size_t numbytes); 257 nifti_image *nifti_read_ascii_image(znzFile fp, char *fname, int flen, 258 int read_data); 259 znzFile nifti_write_ascii_image(nifti_image *nim, const nifti_brick_list * NBL, 260 const char * opts, int write_data, int leave_open); 261 262 263 void nifti_datatype_sizes( int datatype , int *nbyper, int *swapsize ) ; 264 265 void nifti_mat44_to_quatern( mat44 R , 266 float *qb, float *qc, float *qd, 267 float *qx, float *qy, float *qz, 268 float *dx, float *dy, float *dz, float *qfac ) ; 269 270 mat44 nifti_quatern_to_mat44( float qb, float qc, float qd, 271 float qx, float qy, float qz, 272 float dx, float dy, float dz, float qfac ); 273 274 mat44 nifti_make_orthog_mat44( float r11, float r12, float r13 , 275 float r21, float r22, float r23 , 276 float r31, float r32, float r33 ) ; 277 278 int nifti_short_order(void) ; /* CPU byte order */ 279 280 281 /* Orientation codes that might be returned from nifti_mat44_to_orientation().*/ 282 283 #define NIFTI_L2R 1 /* Left to Right */ 284 #define NIFTI_R2L 2 /* Right to Left */ 285 #define NIFTI_P2A 3 /* Posterior to Anterior */ 286 #define NIFTI_A2P 4 /* Anterior to Posterior */ 287 #define NIFTI_I2S 5 /* Inferior to Superior */ 288 #define NIFTI_S2I 6 /* Superior to Inferior */ 289 290 void nifti_mat44_to_orientation( mat44 R , int *icod, int *jcod, int *kcod ) ; 291 292 /*--------------------- Low level IO routines ------------------------------*/ 293 294 char * nifti_findhdrname (const char* fname); 295 char * nifti_findimgname (const char* fname , int nifti_type); 296 int nifti_is_gzfile (const char* fname); 297 298 char * nifti_makebasename(const char* fname); 299 300 301 /* other routines */ 302 struct nifti_1_header nifti_convert_nim2nhdr(const nifti_image* nim); 303 nifti_1_header * nifti_read_header(const char *hname, int *swapped, int check); 304 nifti_image * nifti_copy_nim_info(const nifti_image * src); 305 nifti_image * nifti_simple_init_nim(void); 306 nifti_image * nifti_convert_nhdr2nim(struct nifti_1_header nhdr, 307 const char * fname); 308 309 int nifti_hdr_looks_good (const nifti_1_header * hdr); 310 int nifti_is_valid_ecode (int ecode); 311 int nifti_nim_is_valid (nifti_image * nim, int complain); 312 int nifti_nim_has_valid_dims (nifti_image * nim, int complain); 313 int is_valid_nifti_type (int nifti_type); 314 int nifti_type_and_names_match (nifti_image * nim, int show_warn); 315 int nifti_update_dims_from_array(nifti_image * nim); 316 void nifti_set_iname_offset (nifti_image *nim); 317 int nifti_set_type_from_names (nifti_image * nim); 318 int nifti_add_extension(nifti_image * nim, const char * data, int len, 319 int ecode ); 320 int nifti_copy_extensions (nifti_image *nim_dest,const nifti_image *nim_src); 321 int nifti_free_extensions (nifti_image *nim); 322 int * nifti_get_intlist (int nvals , const char *str); 323 char * nifti_strdup (const char *str); 324 int valid_nifti_extensions(const nifti_image *nim); 325 326 327 /*-------------------- Some C convenience macros ----------------------------*/ 328 329 /* NIfTI-1.1 extension codes: 330 see http://nifti.nimh.nih.gov/nifti-1/documentation/faq#Q21 */ 331 332 #define NIFTI_ECODE_IGNORE 0 /* changed from UNKNOWN, 29 June 2005 */ 333 334 #define NIFTI_ECODE_DICOM 2 /* intended for raw DICOM attributes */ 335 336 #define NIFTI_ECODE_AFNI 4 /* Robert W Cox: rwcox@nih.gov 337 http://afni.nimh.nih.gov/afni */ 338 339 #define NIFTI_ECODE_COMMENT 6 /* plain ASCII text only */ 340 341 #define NIFTI_ECODE_XCEDE 8 /* David B Keator: dbkeator@uci.edu 342 http://www.nbirn.net/Resources 343 /Users/Applications/ 344 /xcede/index.htm */ 345 346 #define NIFTI_ECODE_JIMDIMINFO 10 /* Mark A Horsfield: 347 mah5@leicester.ac.uk 348 http://someplace/something */ 349 350 #define NIFTI_ECODE_WORKFLOW_FWDS 12 /* Kate Fissell: fissel+@pitt.edu 351 http://kraepelin.wpic.pitt.edu 352 /~fissell/NIFTI_ECODE_WORKFLOW_FWDS 353 /NIFTI_ECODE_WORKFLOW_FWDS.html */ 354 355 #define NIFTI_MAX_ECODE 12 /******* maximum extension code *******/ 356 357 /* nifti_type file codes */ 358 #define NIFTI_FTYPE_ANALYZE 0 359 #define NIFTI_FTYPE_NIFTI1_1 1 360 #define NIFTI_FTYPE_NIFTI1_2 2 361 #define NIFTI_FTYPE_ASCII 3 362 #define NIFTI_MAX_FTYPE 3 /* this should match the maximum code */ 363 364 /*------------------------------------------------------------------------*/ 365 /*-- the rest of these apply only to nifti1_io.c, check for _NIFTI1_IO_C_ */ 366 /* Feb 9, 2005 [rickr] */ 367 #ifdef _NIFTI1_IO_C_ 368 369 typedef struct { 370 int debug; /*!< debug level for status reports */ 371 int skip_blank_ext; /*!< skip extender if no extensions */ 372 } nifti_global_options; 373 374 #undef LNI_FERR /* local nifti file error, to be compact and repetative */ 375 #define LNI_FERR(func,msg,file) \ 376 fprintf(stderr,"** ERROR (%s): %s '%s'\n",func,msg,file) 377 378 #undef swap_2 379 #undef swap_4 380 #define swap_2(s) nifti_swap_2bytes(1,&(s)) /* s: 2-byte short; swap in place */ 381 #define swap_4(v) nifti_swap_4bytes(1,&(v)) /* v: 4-byte value; swap in place */ 382 383 /***** isfinite() is a C99 macro, which is 384 present in many C implementations already *****/ 385 386 #undef IS_GOOD_FLOAT 387 #undef FIXED_FLOAT 388 389 #ifdef isfinite /* use isfinite() to check floats/doubles for goodness */ 390 # define IS_GOOD_FLOAT(x) isfinite(x) /* check if x is a "good" float */ 391 # define FIXED_FLOAT(x) (isfinite(x) ? (x) : 0) /* fixed if bad */ 392 #else 393 # define IS_GOOD_FLOAT(x) 1 /* don't check it */ 394 # define FIXED_FLOAT(x) (x) /* don't fix it */ 395 #endif 396 397 #undef ASSIF /* assign v to *p, if possible */ 398 #define ASSIF(p,v) if( (p)!=NULL ) *(p) = (v) 399 400 #undef MSB_FIRST 401 #undef LSB_FIRST 402 #undef REVERSE_ORDER 403 #define LSB_FIRST 1 404 #define MSB_FIRST 2 405 #define REVERSE_ORDER(x) (3-(x)) /* convert MSB_FIRST <--> LSB_FIRST */ 406 407 #define LNI_MAX_NIA_EXT_LEN 100000 /* consider a longer extension invalid */ 408 409 #endif /* _NIFTI1_IO_C_ section */ 410 /*------------------------------------------------------------------------*/ 411 412 /*=================*/ 413 #ifdef __cplusplus 414 } 415 #endif 416 /*=================*/ 417 418 #endif /* _NIFTI_IO_HEADER_ */ 419