nifti1_io.h Source File

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 ( int n , void *ar ) ;
00266 void  nifti_swap_4bytes ( int n , void *ar ) ;
00267 void  nifti_swap_8bytes ( int n , void *ar ) ;
00268 void  nifti_swap_16bytes( int n , void *ar ) ;
00269 void  nifti_swap_Nbytes ( int 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 
00333 int    valid_nifti_brick_list(nifti_image * nim , int nbricks,
00334                               const int * blist, int disp_error);
00335 
00336 /* znzFile operations */
00337 znzFile nifti_image_open(const char * hname, char * opts, nifti_image ** nim);
00338 znzFile nifti_image_write_hdr_img(nifti_image *nim, int write_data,
00339                                   const char* opts);
00340 znzFile nifti_image_write_hdr_img2( nifti_image *nim , int write_opts ,
00341                const char* opts, znzFile imgfile, const nifti_brick_list * NBL);
00342 size_t  nifti_read_buffer(znzFile fp, void* datatptr, size_t ntot,
00343                          nifti_image *nim);
00344 int     nifti_write_all_data(znzFile fp, nifti_image * nim,
00345                              const nifti_brick_list * NBL);
00346 size_t  nifti_write_buffer(znzFile fp, const void * buffer, size_t numbytes);
00347 nifti_image *nifti_read_ascii_image(znzFile fp, char *fname, int flen,
00348                          int read_data);
00349 znzFile nifti_write_ascii_image(nifti_image *nim, const nifti_brick_list * NBL,
00350                          const char * opts, int write_data, int leave_open);
00351 
00352 
00353 void nifti_datatype_sizes( int datatype , int *nbyper, int *swapsize ) ;
00354 
00355 void nifti_mat44_to_quatern( mat44 R ,
00356                              float *qb, float *qc, float *qd,
00357                              float *qx, float *qy, float *qz,
00358                              float *dx, float *dy, float *dz, float *qfac ) ;
00359 
00360 mat44 nifti_quatern_to_mat44( float qb, float qc, float qd,
00361                               float qx, float qy, float qz,
00362                               float dx, float dy, float dz, float qfac );
00363 
00364 mat44 nifti_make_orthog_mat44( float r11, float r12, float r13 ,
00365                                float r21, float r22, float r23 ,
00366                                float r31, float r32, float r33  ) ;
00367 
00368 int nifti_short_order(void) ;              /* CPU byte order */
00369 
00370 
00371 /* Orientation codes that might be returned from nifti_mat44_to_orientation().*/
00372 
00373 #define NIFTI_L2R  1    /* Left to Right         */
00374 #define NIFTI_R2L  2    /* Right to Left         */
00375 #define NIFTI_P2A  3    /* Posterior to Anterior */
00376 #define NIFTI_A2P  4    /* Anterior to Posterior */
00377 #define NIFTI_I2S  5    /* Inferior to Superior  */
00378 #define NIFTI_S2I  6    /* Superior to Inferior  */
00379 
00380 void nifti_mat44_to_orientation( mat44 R , int *icod, int *jcod, int *kcod ) ;
00381 
00382 /*--------------------- Low level IO routines ------------------------------*/
00383 
00384 char * nifti_findhdrname (const char* fname);
00385 char * nifti_findimgname (const char* fname , int nifti_type);
00386 int    nifti_is_gzfile   (const char* fname);
00387 
00388 char * nifti_makebasename(const char* fname);
00389 
00390 
00391 /* other routines */
00392 struct nifti_1_header   nifti_convert_nim2nhdr(const nifti_image* nim);
00393 nifti_1_header * nifti_make_new_header(const int arg_dims[], int arg_dtype);
00394 nifti_1_header * nifti_read_header(const char *hname, int *swapped, int check);
00395 nifti_image    * nifti_copy_nim_info(const nifti_image * src);
00396 nifti_image    * nifti_make_new_nim(const int dims[], int datatype,
00397                                                       int data_fill);
00398 nifti_image    * nifti_simple_init_nim(void);
00399 nifti_image    * nifti_convert_nhdr2nim(struct nifti_1_header nhdr,
00400                                         const char * fname);
00401 
00402 int    nifti_hdr_looks_good        (const nifti_1_header * hdr);
00403 int    nifti_is_valid_datatype     (int dtype);
00404 int    nifti_is_valid_ecode        (int ecode);
00405 int    nifti_nim_is_valid          (nifti_image * nim, int complain);
00406 int    nifti_nim_has_valid_dims    (nifti_image * nim, int complain);
00407 int    is_valid_nifti_type         (int nifti_type);
00408 int    nifti_test_datatype_sizes   (int verb);
00409 int    nifti_type_and_names_match  (nifti_image * nim, int show_warn);
00410 int    nifti_update_dims_from_array(nifti_image * nim);
00411 void   nifti_set_iname_offset      (nifti_image *nim);
00412 int    nifti_set_type_from_names   (nifti_image * nim);
00413 int    nifti_add_extension(nifti_image * nim, const char * data, int len,
00414                            int ecode );
00415 int    nifti_compiled_with_zlib    (void);
00416 int    nifti_copy_extensions (nifti_image *nim_dest,const nifti_image *nim_src);
00417 int    nifti_free_extensions (nifti_image *nim);
00418 int  * nifti_get_intlist     (int nvals , const char *str);
00419 char * nifti_strdup          (const char *str);
00420 int    valid_nifti_extensions(const nifti_image *nim);
00421 
00422 
00423 /*-------------------- Some C convenience macros ----------------------------*/
00424 
00425 /* NIfTI-1.1 extension codes:
00426    see http://nifti.nimh.nih.gov/nifti-1/documentation/faq#Q21 */
00427 
00428 #define NIFTI_ECODE_IGNORE           0  /* changed from UNKNOWN, 29 June 2005 */
00429 
00430 #define NIFTI_ECODE_DICOM            2  /* intended for raw DICOM attributes  */
00431 
00432 #define NIFTI_ECODE_AFNI             4  /* Robert W Cox: rwcox@nih.gov
00433                                            http://afni.nimh.nih.gov/afni      */
00434 
00435 #define NIFTI_ECODE_COMMENT          6  /* plain ASCII text only              */
00436 
00437 #define NIFTI_ECODE_XCEDE            8  /* David B Keator: dbkeator@uci.edu 
00438                                            http://www.nbirn.net/Resources
00439                                                 /Users/Applications/
00440                                                 /xcede/index.htm              */
00441 
00442 #define NIFTI_ECODE_JIMDIMINFO      10  /* Mark A Horsfield:
00443                                            mah5@leicester.ac.uk
00444                                            http://someplace/something         */
00445 
00446 #define NIFTI_ECODE_WORKFLOW_FWDS   12  /* Kate Fissell: fissell@pitt.edu
00447                                            http://kraepelin.wpic.pitt.edu
00448                                             /~fissell/NIFTI_ECODE_WORKFLOW_FWDS
00449                                             /NIFTI_ECODE_WORKFLOW_FWDS.html   */
00450 
00451 #define NIFTI_ECODE_FREESURFER      14  /* http://surfer.nmr.mgh.harvard.edu */
00452 
00453 #define NIFTI_MAX_ECODE             14  /******* maximum extension code *******/
00454 
00455 /* nifti_type file codes */
00456 #define NIFTI_FTYPE_ANALYZE   0
00457 #define NIFTI_FTYPE_NIFTI1_1  1
00458 #define NIFTI_FTYPE_NIFTI1_2  2
00459 #define NIFTI_FTYPE_ASCII     3
00460 #define NIFTI_MAX_FTYPE       3    /* this should match the maximum code */
00461 
00462 /*------------------------------------------------------------------------*/
00463 /*-- the rest of these apply only to nifti1_io.c, check for _NIFTI1_IO_C_ */
00464 /*                                                    Feb 9, 2005 [rickr] */
00465 #ifdef _NIFTI1_IO_C_
00466 
00467 typedef struct {
00468     int debug;               
00469     int skip_blank_ext;      
00470 } nifti_global_options;
00471 
00472 typedef struct {
00473     int    type;           /* should match the NIFTI_TYPE_ #define */
00474     int    nbyper;         /* bytes per value, matches nifti_image */
00475     int    swapsize;       /* bytes per swap piece, matches nifti_image */
00476     char * name;           /* text string to match #define */
00477 } nifti_type_ele;
00478 
00479 #undef  LNI_FERR /* local nifti file error, to be compact and repetative */
00480 #define LNI_FERR(func,msg,file)                                      \
00481             fprintf(stderr,"** ERROR (%s): %s '%s'\n",func,msg,file)
00482 
00483 #undef  swap_2
00484 #undef  swap_4
00485 #define swap_2(s) nifti_swap_2bytes(1,&(s)) /* s: 2-byte short; swap in place */
00486 #define swap_4(v) nifti_swap_4bytes(1,&(v)) /* v: 4-byte value; swap in place */
00487 
00488                         /***** isfinite() is a C99 macro, which is
00489                                present in many C implementations already *****/
00490 
00491 #undef IS_GOOD_FLOAT
00492 #undef FIXED_FLOAT
00493 
00494 #ifdef isfinite       /* use isfinite() to check floats/doubles for goodness */
00495 #  define IS_GOOD_FLOAT(x) isfinite(x)       /* check if x is a "good" float */
00496 #  define FIXED_FLOAT(x)   (isfinite(x) ? (x) : 0)           /* fixed if bad */
00497 #else
00498 #  define IS_GOOD_FLOAT(x) 1                               /* don't check it */
00499 #  define FIXED_FLOAT(x)   (x)                               /* don't fix it */
00500 #endif
00501 
00502 #undef  ASSIF                                 /* assign v to *p, if possible */
00503 #define ASSIF(p,v) if( (p)!=NULL ) *(p) = (v)
00504 
00505 #undef  MSB_FIRST
00506 #undef  LSB_FIRST
00507 #undef  REVERSE_ORDER
00508 #define LSB_FIRST 1
00509 #define MSB_FIRST 2
00510 #define REVERSE_ORDER(x) (3-(x))    /* convert MSB_FIRST <--> LSB_FIRST */
00511 
00512 #define LNI_MAX_NIA_EXT_LEN 100000  /* consider a longer extension invalid */
00513 
00514 #endif  /* _NIFTI1_IO_C_ section */
00515 /*------------------------------------------------------------------------*/
00516 
00517 /*=================*/
00518 #ifdef  __cplusplus
00519 }
00520 #endif
00521 /*=================*/
00522 
00523 #endif /* _NIFTI_IO_HEADER_ */