nifti1_io
|
00001 00006 #ifndef _NIFTI_IO_HEADER_ 00007 #define _NIFTI_IO_HEADER_ 00008 00009 #include <stdio.h> 00010 #include <stdlib.h> 00011 #include <string.h> 00012 #include <math.h> 00013 #include <ctype.h> 00014 00015 #ifndef DONT_INCLUDE_ANALYZE_STRUCT 00016 #define DONT_INCLUDE_ANALYZE_STRUCT /*** not needed herein ***/ 00017 #endif 00018 #include "nifti1.h" /*** NIFTI-1 header specification ***/ 00019 00020 #include <znzlib.h> 00021 00022 /*=================*/ 00023 #ifdef __cplusplus 00024 extern "C" { 00025 #endif 00026 /*=================*/ 00027 00028 /*****===================================================================*****/ 00029 /***** File nifti1_io.h == Declarations for nifti1_io.c *****/ 00030 /*****...................................................................*****/ 00031 /***** This code is released to the public domain. *****/ 00032 /*****...................................................................*****/ 00033 /***** Author: Robert W Cox, SSCC/DIRP/NIMH/NIH/DHHS/USA/EARTH *****/ 00034 /***** Date: August 2003 *****/ 00035 /*****...................................................................*****/ 00036 /***** Neither the National Institutes of Health (NIH), nor any of its *****/ 00037 /***** employees imply any warranty of usefulness of this software for *****/ 00038 /***** any purpose, and do not assume any liability for damages, *****/ 00039 /***** incidental or otherwise, caused by any use of this document. *****/ 00040 /*****===================================================================*****/ 00041 00042 /* 00043 Modified by: Mark Jenkinson (FMRIB Centre, University of Oxford, UK) 00044 Date: July/August 2004 00045 00046 Mainly adding low-level IO and changing things to allow gzipped files 00047 to be read and written 00048 Full backwards compatability should have been maintained 00049 00050 Modified by: Rick Reynolds (SSCC/DIRP/NIMH, National Institutes of Health) 00051 Date: December 2004 00052 00053 Modified and added many routines for I/O. 00054 */ 00055 00056 /********************** Some sample data structures **************************/ 00057 00058 typedef struct { 00059 float m[4][4] ; 00060 } mat44 ; 00061 00062 typedef struct { 00063 float m[3][3] ; 00064 } mat33 ; 00065 00066 /*...........................................................................*/ 00067 00072 typedef enum _analyze75_orient_code { 00073 a75_transverse_unflipped = 0, 00074 a75_coronal_unflipped = 1, 00075 a75_sagittal_unflipped = 2, 00076 a75_transverse_flipped = 3, 00077 a75_coronal_flipped = 4, 00078 a75_sagittal_flipped = 5, 00079 a75_orient_unknown = 6 00080 } analyze_75_orient_code; 00081 00088 typedef struct { 00090 int ndim ; 00091 int nx ; 00092 int ny ; 00093 int nz ; 00094 int nt ; 00095 int nu ; 00096 int nv ; 00097 int nw ; 00098 int dim[8] ; 00099 size_t nvox ; 00100 int nbyper ; 00101 int datatype ; 00103 float dx ; 00104 float dy ; 00105 float dz ; 00106 float dt ; 00107 float du ; 00108 float dv ; 00109 float dw ; 00110 float pixdim[8] ; 00112 float scl_slope ; 00113 float scl_inter ; 00115 float cal_min ; 00116 float cal_max ; 00118 int qform_code ; 00119 int sform_code ; 00121 int freq_dim ; 00122 int phase_dim ; 00123 int slice_dim ; 00125 int slice_code ; 00126 int slice_start ; 00127 int slice_end ; 00128 float slice_duration ; 00132 float quatern_b , quatern_c , quatern_d , 00133 qoffset_x , qoffset_y , qoffset_z , 00134 qfac ; 00135 00136 mat44 qto_xyz ; 00137 mat44 qto_ijk ; 00139 mat44 sto_xyz ; 00140 mat44 sto_ijk ; 00142 float toffset ; 00144 int xyz_units ; 00145 int time_units ; 00147 int nifti_type ; 00150 int intent_code ; 00151 float intent_p1 ; 00152 float intent_p2 ; 00153 float intent_p3 ; 00154 char intent_name[16] ; 00156 char descrip[80] ; 00157 char aux_file[24] ; 00159 char *fname ; 00160 char *iname ; 00161 int iname_offset ; 00162 int swapsize ; 00163 int byteorder ; 00164 void *data ; 00166 int num_ext ; 00167 nifti1_extension * ext_list ; 00168 analyze_75_orient_code analyze75_orient; 00170 } nifti_image ; 00171 00172 00173 00174 /* struct for return from nifti_image_read_bricks() */ 00175 typedef struct { 00176 int nbricks; /* the number of allocated pointers in 'bricks' */ 00177 size_t bsize; /* the length of each data block, in bytes */ 00178 void ** bricks; /* array of pointers to data blocks */ 00179 } nifti_brick_list; 00180 00181 00182 /*****************************************************************************/ 00183 /*------------------ NIfTI version of ANALYZE 7.5 structure -----------------*/ 00184 00185 /* (based on fsliolib/dbh.h, but updated for version 7.5) */ 00186 00187 typedef struct { 00188 /* header info fields - describes the header overlap with NIfTI */ 00189 /* ------------------ */ 00190 int sizeof_hdr; /* 0 + 4 same */ 00191 char data_type[10]; /* 4 + 10 same */ 00192 char db_name[18]; /* 14 + 18 same */ 00193 int extents; /* 32 + 4 same */ 00194 short int session_error; /* 36 + 2 same */ 00195 char regular; /* 38 + 1 same */ 00196 char hkey_un0; /* 39 + 1 40 bytes */ 00197 00198 /* image dimension fields - describes image sizes */ 00199 short int dim[8]; /* 0 + 16 same */ 00200 short int unused8; /* 16 + 2 intent_p1... */ 00201 short int unused9; /* 18 + 2 ... */ 00202 short int unused10; /* 20 + 2 intent_p2... */ 00203 short int unused11; /* 22 + 2 ... */ 00204 short int unused12; /* 24 + 2 intent_p3... */ 00205 short int unused13; /* 26 + 2 ... */ 00206 short int unused14; /* 28 + 2 intent_code */ 00207 short int datatype; /* 30 + 2 same */ 00208 short int bitpix; /* 32 + 2 same */ 00209 short int dim_un0; /* 34 + 2 slice_start */ 00210 float pixdim[8]; /* 36 + 32 same */ 00211 00212 float vox_offset; /* 68 + 4 same */ 00213 float funused1; /* 72 + 4 scl_slope */ 00214 float funused2; /* 76 + 4 scl_inter */ 00215 float funused3; /* 80 + 4 slice_end, */ 00216 /* slice_code, */ 00217 /* xyzt_units */ 00218 float cal_max; /* 84 + 4 same */ 00219 float cal_min; /* 88 + 4 same */ 00220 float compressed; /* 92 + 4 slice_duration */ 00221 float verified; /* 96 + 4 toffset */ 00222 int glmax,glmin; /* 100 + 8 108 bytes */ 00223 00224 /* data history fields - optional */ 00225 char descrip[80]; /* 0 + 80 same */ 00226 char aux_file[24]; /* 80 + 24 same */ 00227 char orient; /* 104 + 1 NO GOOD OVERLAP */ 00228 char originator[10]; /* 105 + 10 FROM HERE DOWN... */ 00229 char generated[10]; /* 115 + 10 */ 00230 char scannum[10]; /* 125 + 10 */ 00231 char patient_id[10]; /* 135 + 10 */ 00232 char exp_date[10]; /* 145 + 10 */ 00233 char exp_time[10]; /* 155 + 10 */ 00234 char hist_un0[3]; /* 165 + 3 */ 00235 int views; /* 168 + 4 */ 00236 int vols_added; /* 172 + 4 */ 00237 int start_field; /* 176 + 4 */ 00238 int field_skip; /* 180 + 4 */ 00239 int omax, omin; /* 184 + 8 */ 00240 int smax, smin; /* 192 + 8 200 bytes */ 00241 } nifti_analyze75; /* total: 348 bytes */ 00242 00243 00244 /*****************************************************************************/ 00245 /*--------------- Prototypes of functions defined in this file --------------*/ 00246 00247 char *nifti_datatype_string ( int dt ) ; 00248 char *nifti_units_string ( int uu ) ; 00249 char *nifti_intent_string ( int ii ) ; 00250 char *nifti_xform_string ( int xx ) ; 00251 char *nifti_slice_string ( int ss ) ; 00252 char *nifti_orientation_string( int ii ) ; 00253 00254 int nifti_is_inttype( int dt ) ; 00255 00256 mat44 nifti_mat44_inverse( mat44 R ) ; 00257 00258 mat33 nifti_mat33_inverse( mat33 R ) ; 00259 mat33 nifti_mat33_polar ( mat33 A ) ; 00260 float nifti_mat33_rownorm( mat33 A ) ; 00261 float nifti_mat33_colnorm( mat33 A ) ; 00262 float nifti_mat33_determ ( mat33 R ) ; 00263 mat33 nifti_mat33_mul ( mat33 A , mat33 B ) ; 00264 00265 void nifti_swap_2bytes ( size_t n , void *ar ) ; 00266 void nifti_swap_4bytes ( size_t n , void *ar ) ; 00267 void nifti_swap_8bytes ( size_t n , void *ar ) ; 00268 void nifti_swap_16bytes( size_t n , void *ar ) ; 00269 void nifti_swap_Nbytes ( size_t n , int siz , void *ar ) ; 00270 00271 int nifti_datatype_is_valid (int dtype, int for_nifti); 00272 int nifti_datatype_from_string(const char * name); 00273 char * nifti_datatype_to_string (int dtype); 00274 00275 int nifti_get_filesize( const char *pathname ) ; 00276 void swap_nifti_header ( struct nifti_1_header *h , int is_nifti ) ; 00277 void old_swap_nifti_header( struct nifti_1_header *h , int is_nifti ); 00278 int nifti_swap_as_analyze( nifti_analyze75 *h ); 00279 00280 00281 /* main read/write routines */ 00282 00283 nifti_image *nifti_image_read_bricks(const char *hname , int nbricks, 00284 const int *blist, nifti_brick_list * NBL); 00285 int nifti_image_load_bricks(nifti_image *nim , int nbricks, 00286 const int *blist, nifti_brick_list * NBL); 00287 void nifti_free_NBL( nifti_brick_list * NBL ); 00288 00289 nifti_image *nifti_image_read ( const char *hname , int read_data ) ; 00290 int nifti_image_load ( nifti_image *nim ) ; 00291 void nifti_image_unload ( nifti_image *nim ) ; 00292 void nifti_image_free ( nifti_image *nim ) ; 00293 00294 int nifti_read_collapsed_image( nifti_image * nim, const int dims [8], 00295 void ** data ); 00296 00297 int nifti_read_subregion_image( nifti_image * nim, 00298 int *start_index, int *region_size, 00299 void ** data ); 00300 00301 void nifti_image_write ( nifti_image * nim ) ; 00302 void nifti_image_write_bricks(nifti_image * nim, 00303 const nifti_brick_list * NBL); 00304 void nifti_image_infodump( const nifti_image * nim ) ; 00305 00306 void nifti_disp_lib_hist( void ) ; /* to display library history */ 00307 void nifti_disp_lib_version( void ) ; /* to display library version */ 00308 int nifti_disp_matrix_orient( const char * mesg, mat44 mat ); 00309 int nifti_disp_type_list( int which ); 00310 00311 00312 char * nifti_image_to_ascii ( const nifti_image * nim ) ; 00313 nifti_image *nifti_image_from_ascii( const char * str, int * bytes_read ) ; 00314 00315 size_t nifti_get_volsize(const nifti_image *nim) ; 00316 00317 /* basic file operations */ 00318 int nifti_set_filenames(nifti_image * nim, const char * prefix, int check, 00319 int set_byte_order); 00320 char * nifti_makehdrname (const char * prefix, int nifti_type, int check, 00321 int comp); 00322 char * nifti_makeimgname (const char * prefix, int nifti_type, int check, 00323 int comp); 00324 int is_nifti_file (const char *hname); 00325 char * nifti_find_file_extension(const char * name); 00326 int nifti_is_complete_filename(const char* fname); 00327 int nifti_validfilename(const char* fname); 00328 00329 int disp_nifti_1_header(const char * info, const nifti_1_header * hp ) ; 00330 void nifti_set_debug_level( int level ) ; 00331 void nifti_set_skip_blank_ext( int skip ) ; 00332 void nifti_set_allow_upper_fext( int allow ) ; 00333 00334 int valid_nifti_brick_list(nifti_image * nim , int nbricks, 00335 const int * blist, int disp_error); 00336 00337 /* znzFile operations */ 00338 znzFile nifti_image_open(const char * hname, char * opts, nifti_image ** nim); 00339 znzFile nifti_image_write_hdr_img(nifti_image *nim, int write_data, 00340 const char* opts); 00341 znzFile nifti_image_write_hdr_img2( nifti_image *nim , int write_opts , 00342 const char* opts, znzFile imgfile, const nifti_brick_list * NBL); 00343 size_t nifti_read_buffer(znzFile fp, void* datatptr, size_t ntot, 00344 nifti_image *nim); 00345 int nifti_write_all_data(znzFile fp, nifti_image * nim, 00346 const nifti_brick_list * NBL); 00347 size_t nifti_write_buffer(znzFile fp, const void * buffer, size_t numbytes); 00348 nifti_image *nifti_read_ascii_image(znzFile fp, char *fname, int flen, 00349 int read_data); 00350 znzFile nifti_write_ascii_image(nifti_image *nim, const nifti_brick_list * NBL, 00351 const char * opts, int write_data, int leave_open); 00352 00353 00354 void nifti_datatype_sizes( int datatype , int *nbyper, int *swapsize ) ; 00355 00356 void nifti_mat44_to_quatern( mat44 R , 00357 float *qb, float *qc, float *qd, 00358 float *qx, float *qy, float *qz, 00359 float *dx, float *dy, float *dz, float *qfac ) ; 00360 00361 mat44 nifti_quatern_to_mat44( float qb, float qc, float qd, 00362 float qx, float qy, float qz, 00363 float dx, float dy, float dz, float qfac ); 00364 00365 mat44 nifti_make_orthog_mat44( float r11, float r12, float r13 , 00366 float r21, float r22, float r23 , 00367 float r31, float r32, float r33 ) ; 00368 00369 int nifti_short_order(void) ; /* CPU byte order */ 00370 00371 00372 /* Orientation codes that might be returned from nifti_mat44_to_orientation().*/ 00373 00374 #define NIFTI_L2R 1 /* Left to Right */ 00375 #define NIFTI_R2L 2 /* Right to Left */ 00376 #define NIFTI_P2A 3 /* Posterior to Anterior */ 00377 #define NIFTI_A2P 4 /* Anterior to Posterior */ 00378 #define NIFTI_I2S 5 /* Inferior to Superior */ 00379 #define NIFTI_S2I 6 /* Superior to Inferior */ 00380 00381 void nifti_mat44_to_orientation( mat44 R , int *icod, int *jcod, int *kcod ) ; 00382 00383 /*--------------------- Low level IO routines ------------------------------*/ 00384 00385 char * nifti_findhdrname (const char* fname); 00386 char * nifti_findimgname (const char* fname , int nifti_type); 00387 int nifti_is_gzfile (const char* fname); 00388 00389 char * nifti_makebasename(const char* fname); 00390 00391 00392 /* other routines */ 00393 struct nifti_1_header nifti_convert_nim2nhdr(const nifti_image* nim); 00394 nifti_1_header * nifti_make_new_header(const int arg_dims[], int arg_dtype); 00395 nifti_1_header * nifti_read_header(const char *hname, int *swapped, int check); 00396 nifti_image * nifti_copy_nim_info(const nifti_image * src); 00397 nifti_image * nifti_make_new_nim(const int dims[], int datatype, 00398 int data_fill); 00399 nifti_image * nifti_simple_init_nim(void); 00400 nifti_image * nifti_convert_nhdr2nim(struct nifti_1_header nhdr, 00401 const char * fname); 00402 00403 int nifti_hdr_looks_good (const nifti_1_header * hdr); 00404 int nifti_is_valid_datatype (int dtype); 00405 int nifti_is_valid_ecode (int ecode); 00406 int nifti_nim_is_valid (nifti_image * nim, int complain); 00407 int nifti_nim_has_valid_dims (nifti_image * nim, int complain); 00408 int is_valid_nifti_type (int nifti_type); 00409 int nifti_test_datatype_sizes (int verb); 00410 int nifti_type_and_names_match (nifti_image * nim, int show_warn); 00411 int nifti_update_dims_from_array(nifti_image * nim); 00412 void nifti_set_iname_offset (nifti_image *nim); 00413 int nifti_set_type_from_names (nifti_image * nim); 00414 int nifti_add_extension(nifti_image * nim, const char * data, int len, 00415 int ecode ); 00416 int nifti_compiled_with_zlib (void); 00417 int nifti_copy_extensions (nifti_image *nim_dest,const nifti_image *nim_src); 00418 int nifti_free_extensions (nifti_image *nim); 00419 int * nifti_get_intlist (int nvals , const char *str); 00420 char * nifti_strdup (const char *str); 00421 int valid_nifti_extensions(const nifti_image *nim); 00422 00423 00424 /*-------------------- Some C convenience macros ----------------------------*/ 00425 00426 /* NIfTI-1.1 extension codes: 00427 see http://nifti.nimh.nih.gov/nifti-1/documentation/faq#Q21 */ 00428 00429 #define NIFTI_ECODE_IGNORE 0 /* changed from UNKNOWN, 29 June 2005 */ 00430 00431 #define NIFTI_ECODE_DICOM 2 /* intended for raw DICOM attributes */ 00432 00433 #define NIFTI_ECODE_AFNI 4 /* Robert W Cox: rwcox@nih.gov 00434 http://afni.nimh.nih.gov/afni */ 00435 00436 #define NIFTI_ECODE_COMMENT 6 /* plain ASCII text only */ 00437 00438 #define NIFTI_ECODE_XCEDE 8 /* David B Keator: dbkeator@uci.edu 00439 http://www.nbirn.net/Resources 00440 /Users/Applications/ 00441 /xcede/index.htm */ 00442 00443 #define NIFTI_ECODE_JIMDIMINFO 10 /* Mark A Horsfield: 00444 mah5@leicester.ac.uk 00445 http://someplace/something */ 00446 00447 #define NIFTI_ECODE_WORKFLOW_FWDS 12 /* Kate Fissell: fissell@pitt.edu 00448 http://kraepelin.wpic.pitt.edu 00449 /~fissell/NIFTI_ECODE_WORKFLOW_FWDS 00450 /NIFTI_ECODE_WORKFLOW_FWDS.html */ 00451 00452 #define NIFTI_ECODE_FREESURFER 14 /* http://surfer.nmr.mgh.harvard.edu */ 00453 00454 #define NIFTI_ECODE_PYPICKLE 16 /* embedded Python objects 00455 http://niftilib.sourceforge.net 00456 /pynifti */ 00457 00458 /* LONI MiND codes: http://www.loni.ucla.edu/twiki/bin/view/Main/MiND */ 00459 #define NIFTI_ECODE_MIND_IDENT 18 /* Vishal Patel: vishal.patel@ucla.edu*/ 00460 #define NIFTI_ECODE_B_VALUE 20 00461 #define NIFTI_ECODE_SPHERICAL_DIRECTION 22 00462 #define NIFTI_ECODE_DT_COMPONENT 24 00463 #define NIFTI_ECODE_SHC_DEGREEORDER 26 /* end LONI MiND codes */ 00464 00465 #define NIFTI_ECODE_VOXBO 28 /* Dan Kimberg: www.voxbo.org */ 00466 00467 #define NIFTI_ECODE_CARET 30 /* John Harwell: john@brainvis.wustl.edu 00468 http://brainvis.wustl.edu/wiki 00469 /index.php/Caret:Documentation 00470 :CaretNiftiExtension */ 00471 00472 #define NIFTI_MAX_ECODE 30 /******* maximum extension code *******/ 00473 00474 /* nifti_type file codes */ 00475 #define NIFTI_FTYPE_ANALYZE 0 00476 #define NIFTI_FTYPE_NIFTI1_1 1 00477 #define NIFTI_FTYPE_NIFTI1_2 2 00478 #define NIFTI_FTYPE_ASCII 3 00479 #define NIFTI_MAX_FTYPE 3 /* this should match the maximum code */ 00480 00481 /*------------------------------------------------------------------------*/ 00482 /*-- the rest of these apply only to nifti1_io.c, check for _NIFTI1_IO_C_ */ 00483 /* Feb 9, 2005 [rickr] */ 00484 #ifdef _NIFTI1_IO_C_ 00485 00486 typedef struct { 00487 int debug; 00488 int skip_blank_ext; 00489 int allow_upper_fext; 00490 } nifti_global_options; 00491 00492 typedef struct { 00493 int type; /* should match the NIFTI_TYPE_ #define */ 00494 int nbyper; /* bytes per value, matches nifti_image */ 00495 int swapsize; /* bytes per swap piece, matches nifti_image */ 00496 char * name; /* text string to match #define */ 00497 } nifti_type_ele; 00498 00499 #undef LNI_FERR /* local nifti file error, to be compact and repetative */ 00500 #define LNI_FERR(func,msg,file) \ 00501 fprintf(stderr,"** ERROR (%s): %s '%s'\n",func,msg,file) 00502 00503 #undef swap_2 00504 #undef swap_4 00505 #define swap_2(s) nifti_swap_2bytes(1,&(s)) /* s: 2-byte short; swap in place */ 00506 #define swap_4(v) nifti_swap_4bytes(1,&(v)) /* v: 4-byte value; swap in place */ 00507 00508 /***** isfinite() is a C99 macro, which is 00509 present in many C implementations already *****/ 00510 00511 #undef IS_GOOD_FLOAT 00512 #undef FIXED_FLOAT 00513 00514 #ifdef isfinite /* use isfinite() to check floats/doubles for goodness */ 00515 # define IS_GOOD_FLOAT(x) isfinite(x) /* check if x is a "good" float */ 00516 # define FIXED_FLOAT(x) (isfinite(x) ? (x) : 0) /* fixed if bad */ 00517 #else 00518 # define IS_GOOD_FLOAT(x) 1 /* don't check it */ 00519 # define FIXED_FLOAT(x) (x) /* don't fix it */ 00520 #endif 00521 00522 #undef ASSIF /* assign v to *p, if possible */ 00523 #define ASSIF(p,v) if( (p)!=NULL ) *(p) = (v) 00524 00525 #undef MSB_FIRST 00526 #undef LSB_FIRST 00527 #undef REVERSE_ORDER 00528 #define LSB_FIRST 1 00529 #define MSB_FIRST 2 00530 #define REVERSE_ORDER(x) (3-(x)) /* convert MSB_FIRST <--> LSB_FIRST */ 00531 00532 #define LNI_MAX_NIA_EXT_LEN 100000 /* consider a longer extension invalid */ 00533 00534 #endif /* _NIFTI1_IO_C_ section */ 00535 /*------------------------------------------------------------------------*/ 00536 00537 /*=================*/ 00538 #ifdef __cplusplus 00539 } 00540 #endif 00541 /*=================*/ 00542 00543 #endif /* _NIFTI_IO_HEADER_ */