nifti1_io
fslio.h
Go to the documentation of this file.
1 
5 /*
6  fslio.h (Input and output routines for images in FSL)
7 
8  Mark Jenkinson
9  FMRIB Image Analysis Group
10 
11 */
12 
13 
14 /*
15  The fslio.h file was originally part of FSL - FMRIB's Software Library
16  http://www.fmrib.ox.ac.uk/fsl
17  fslio.h has now been placed in the public domain.
18 
19  Developed at FMRIB (Oxford Centre for Functional Magnetic Resonance
20  Imaging of the Brain), Department of Clinical Neurology, Oxford
21  University, Oxford, UK
22 */
23 
24 #if !defined(__FSLIO_H)
25 #define __FSLIO_H
26 
27 #include <stdio.h>
28 #include <nifti1_io.h>
29 #include <znzlib.h>
30 #include "dbh.h"
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
36 
37  /*
38  Note that this library is similar to avwio but has changed in many ways.
39  It is almost fully backwards compatible, but not quite, as it cannot write
40  .nii.gz files using the old style functions.
41 
42  Recommended ways of reading and writing images are:
43 
44  Reading
45  -------
46  Use the FslOpen(), FslReadVolumes() and FslClose() functions. e.g.
47  FSLIO *fslio;
48  void *buffer;
49  int nvols;
50  fslio = FslOpen("/some/path/name_of_file","rb");
51  ... can now access header info via the FslGet calls ...
52  ... allocate room for buffer ...
53  FslReadVolumes(fslio,buffer,nvols);
54  ... do something ...
55  FslClose(fslio);
56 
57 
58  Writing
59  -------
60  This is more complicated due to the nature of gzipped writing, which must be
61  done in the correct order, and for single files (*.nii.gz) this means that
62  the header information must be written before any image data.
63 
64  (1)
65  The best method to use is almost backwards compatible, but requires
66  an FslWriteHeader() call:
67 
68  FSLIO* fslio;
69  fslio = FslOpen("/some/path/name_of_file","wb");
70  ... set the appropriate header information using FslSet calls ...
71  FslWriteHeader(fslio);
72 
73  ... now can write one or more volumes at a time using
74  FslWriteVolumes(fslio,buffer,nvols) ...
75 
76  FslClose(fslio);
77 
78  This version is useful if your image data needs to be written from different blocks
79  of memory.
80 
81  (2)
82  Another method is available, but which is discouraged, is:
83  FSLIO* fslio;
84  fslio = FslOpen("/some/path/name_of_file","wb");
85 
86  ... set some appropriate header information using FslSet calls ...
87  ... now can write one or more volumes at a time using
88  FslWriteVolumes(fslio,buffer,nvols) ...
89  ... set more appropriate header information using FslSet calls ...
90 
91  FslClose(fslio);
92 
93  WARNING: this cannot write .nii.gz files as the header information cannot be
94  written by FslClose() after the image data is written, which is how the previous
95  versions have worked.
96 
97 
98  */
99 
104 #define FSL_TYPE_ANALYZE 0
105 #define FSL_TYPE_NIFTI 1
106 #define FSL_TYPE_NIFTI_PAIR 2
107 #define FSL_TYPE_MINC 4
108 #define FSL_TYPE_ANALYZE_GZ 100
109 #define FSL_TYPE_NIFTI_GZ 101
110 #define FSL_TYPE_NIFTI_PAIR_GZ 102
111 #define FSL_TYPE_MINC_GZ 104
112 /* @} */
113 
114 #define FSL_RADIOLOGICAL -1
115 #define FSL_NEUROLOGICAL 1
116 
117 
123 typedef struct
124 {
125  znzFile fileptr;
126  nifti_image *niftiptr;
127 #ifdef USE_MINC
128  minc_image *mincptr;
129 #else
130  void *mincptr;
131 #endif
132  int file_mode;
133  int write_mode;
134  int written_hdr;
135 } FSLIO;
136 
137 
138  /* basic file i/o commands */
139 
140 FSLIO *FslOpen(const char *filename, const char *opts);
141 FSLIO *FslXOpen(const char *filename, const char *opts, int filetype);
142 int FslSeekVolume(FSLIO *fslio, size_t vols);
143 int FslClose(FSLIO *fslio);
144 
145  /* basic read and write commands */
146 
147 void* FslReadAllVolumes(FSLIO* fslio, char* filename);
148 void FslWriteAllVolumes(FSLIO *fslio, const void *buffer);
149 
150 size_t FslReadVolumes(FSLIO *fslio, void *buffer, size_t nvols);
151 size_t FslWriteVolumes(FSLIO *fslio, const void *buffer, size_t nvols);
152 
153 void FslWriteHeader(FSLIO *fslio);
154 
155  /* support functions for file names and types */
156 
157 int FslFileExists(const char *filename);
158 char *FslMakeBaseName(const char *fname);
159 int FslCheckForMultipleFileNames(const char* filename);
160 int FslGetEnvOutputType(void);
161 
162 void FslSetIgnoreMFQ(int flag);
163 int FslGetIgnoreMFQ(void);
164 void FslSetOverrideOutputType(int type);
165 int FslGetOverrideOutputType(void);
166 
167 
168 int FslGetFileType(const FSLIO *fslio);
169 void FslSetFileType(FSLIO *fslio, int filetype);
170 int FslIsSingleFileType(int filetype);
171 int FslIsCompressedFileType(int filetype);
172 int FslBaseFileType(int filetype);
173 const char* FslFileTypeString(int filetype);
174 
175 int FslGetWriteMode(const FSLIO *fslio);
176 void FslSetWriteMode(FSLIO *fslio, int mode);
177 
178 void AvwSwapHeader(struct dsr *avw);
179 int FslReadRawHeader(void *buffer, const char* filename);
180 
181 
182  /* simple creation and clone/copy operations */
183 
184 FSLIO *FslInit(void);
185 void FslInitHeader(FSLIO *fslio, short t,
186  size_t x, size_t y, size_t z, size_t v,
187  float vx, float vy, float vz, float tr,
188  size_t dim);
189 void FslSetInit(FSLIO* fslio);
190 void FslCloneHeader(FSLIO *dest, const FSLIO *src);
191 
192 
193  /* get and set routines for properties */
194 
195 size_t FslGetVolSize(FSLIO *fslio);
196 
197 void FslSetDim(FSLIO *fslio, short x, short y, short z, short v);
198 void FslGetDim(FSLIO *fslio, short *x, short *y, short *z, short *v);
199 void FslSetDimensionality(FSLIO *fslio, size_t dim);
200 void FslGetDimensionality(FSLIO *fslio, size_t *dim);
201 void FslSetVoxDim(FSLIO *fslio, float x, float y, float z, float tr);
202 void FslGetVoxDim(FSLIO *fslio, float *x, float *y, float *z, float *tr);
203 void FslGetCalMinMax(FSLIO *fslio, float *min, float *max);
204 void FslSetCalMinMax(FSLIO *fslio, float min, float max);
205 void FslGetAuxFile(FSLIO *fslio,char *aux_file);
206 void FslSetAuxFile(FSLIO *fslio,const char *aux_file);
207 void FslSetTimeUnits(FSLIO *fslio, const char *units);
208 void FslGetTimeUnits(FSLIO *fslio, char *units);
209 void FslSetDataType(FSLIO *fslio, short t);
210 size_t FslGetDataType(FSLIO *fslio, short *t);
211 int FslGetIntensityScaling(FSLIO *fslio, float *slope, float *intercept);
212 void FslSetIntent(FSLIO *fslio, short intent_code, float p1, float p2, float p3);
213 short FslGetIntent(FSLIO *fslio, short *intent_code, float *p1, float *p2,
214  float *p3);
215 
216 
217 short FslGetStdXform(FSLIO *fslio, mat44 *stdmat);
218 void FslSetStdXform(FSLIO *fslio, short sform_code, mat44 stdmat);
219 void FslGetMMCoord(mat44 stdmat, float voxx, float voxy, float voxz,
220  float *mmx, float *mmy, float *mmz);
221 
222 void FslGetVoxCoord(mat44 stdmat, float mmx, float mmy, float mmz,
223  float *voxx, float *voxy, float *voxz);
224 short FslGetRigidXform(FSLIO *fslio, mat44 *rigidmat);
225 void FslSetRigidXform(FSLIO *fslio, short qform_code, mat44 rigidmat);
226 int FslGetLeftRightOrder(FSLIO *fslio);
227 
228  /* these two functions are deprecated with the nifti/analyze support */
229  /* please do all spatial coordinate origins via the Std and Rigid Xforms */
230 void FslSetAnalyzeSform(FSLIO *fslio, const short *orig,
231  float dx, float dy, float dz);
232 void FslGetAnalyzeOrigin(FSLIO *fslio, short orig[5]);
233 
234  /* other read and write commands */
235 
236 size_t FslReadSliceSeries(FSLIO *fslio, void *buffer,short slice, size_t nvols);
237 size_t FslReadRowSeries(FSLIO *fslio, void *buffer, short row, short slice, size_t nvols);
238 size_t FslReadTimeSeries(FSLIO *fslio, void *buffer, short xVox, short yVox, short zVox, size_t nvols);
239 
240  /* miscellaneous helper stuff */
241 
242 mat33 mat44_to_mat33(mat44 x);
243 
244 
245 
246 /* added by KF pending discussion w/ Mark */
247 typedef unsigned char THIS_UINT8;
248 typedef char THIS_INT8;
249 typedef unsigned short THIS_UINT16;
250 typedef short THIS_INT16;
251 typedef unsigned int THIS_UINT32;
252 typedef int THIS_INT32;
253 typedef unsigned long THIS_UINT64;
254 typedef long THIS_INT64;
255 typedef float THIS_FLOAT32;
256 typedef double THIS_FLOAT64;
257 
258 FSLIO * FslReadHeader(char *fname);
259 double ****FslGetBufferAsScaledDouble(FSLIO *fslio);
260 double ***FslGetVolumeAsScaledDouble(FSLIO *fslio, int vol);
261 int convertBufferToScaledDouble(double *outbuf, void *inbuf, long len, float slope, float inter, int nifti_datatype ) ;
262 double ****d4matrix(int th, int zh, int yh, int xh);
263 double ***d3matrix(int zh, int yh, int xh);
264 
265 
266 #ifdef __cplusplus
267 }
268 #endif
269 
270 #endif
void * FslReadAllVolumes(FSLIO *fslio, char *filename)
Read the header and all data into the FSLIO structure.
Definition: fslio.c:789
double *** FslGetVolumeAsScaledDouble(FSLIO *fslio, int vol)
Return volume #vol (0-based) as a 3D array of scaled doubles.
Definition: fslio.c:2117
double **** d4matrix(int th, int zh, int yh, int xh)
allocate a 4D buffer, use 1 contiguous buffer for the data
Definition: fslio.c:2392
const char * FslFileTypeString(int filetype)
Return a string describing the format of the dataset.
Definition: fslio.c:47
int FslClose(FSLIO *fslio)
Write header and image data if this dataset was open for writing. Close the dataset header and data f...
Definition: fslio.c:1906
FSLIO * FslOpen(const char *filename, const char *opts)
Opens a file for either reading or writing.
Definition: fslio.c:624
FSLIO * FslReadHeader(char *fname)
Reads nifti/anz header, no data is read.
Definition: fslio.c:2075
double **** FslGetBufferAsScaledDouble(FSLIO *fslio)
Return the fslio data buffer of a 1-4D dataset as a 4D array of scaled doubles.
Definition: fslio.c:2204
void FslWriteHeader(FSLIO *fslio)
Writes nifti/anz header and opens img file ready for writing.
Definition: fslio.c:954
size_t FslReadTimeSeries(FSLIO *fslio, void *buffer, short xVox, short yVox, short zVox, size_t nvols)
Read one voxel (xyz location) from first nvols volumes in dataset; ie get a t dim buffer.
Definition: fslio.c:1114
void FslWriteAllVolumes(FSLIO *fslio, const void *buffer)
Writes all data from buffer (using size info from fslio) to file.
Definition: fslio.c:868
double *** d3matrix(int zh, int yh, int xh)
allocate a 3D buffer, use 1 contiguous buffer for the data
Definition: fslio.c:2343
FSLIO * FslInit(void)
allocate space for the FSLIO struct and set some sensible defaults
Definition: fslio.c:372
size_t FslReadRowSeries(FSLIO *fslio, void *buffer, short row, short slice, size_t nvols)
Read one row from one slice for first nvols volumes in dataset; ie get an xt buffer.
Definition: fslio.c:1055
size_t FslReadSliceSeries(FSLIO *fslio, void *buffer, short slice, size_t nvols)
Read one slice from each of the first nvols volumes in the dataset, ie get an xyt buffer.
Definition: fslio.c:998
int convertBufferToScaledDouble(double *outbuf, void *inbuf, long len, float slope, float inter, int nifti_datatype)
allocate a 4D buffer, use 1 contiguous buffer for the data
Definition: fslio.c:2275
FSLIO * FslXOpen(const char *filename, const char *opts, int filetype)
Opens a file for either reading or writing.
Definition: fslio.c:652
size_t FslReadVolumes(FSLIO *fslio, void *buffer, size_t nvols)
Read the first nvols Volumes from a 4D dataset.
Definition: fslio.c:833
size_t FslWriteVolumes(FSLIO *fslio, const void *buffer, size_t nvols)
Write the first nvols volumes in buffer to disk.
Definition: fslio.c:899
Data structures for using nifti1_io API.
High level data structure for open datasets in the fslio API.
Definition: fslio.h:124
Definition: dbh.h:76
Definition: nifti1_io.h:62
Definition: nifti1_io.h:58
High level data structure for open nifti datasets in the nifti1_io API. Note that this structure is n...
Definition: nifti1_io.h:88
Definition: znzlib.h:79