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 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  const char* units);
190 void FslSetInit(FSLIO* fslio);
191 void FslCloneHeader(FSLIO *dest, const FSLIO *src);
192 
193 
194  /* get and set routines for properties */
195 
196 size_t FslGetVolSize(FSLIO *fslio);
197 
198 void FslSetDim(FSLIO *fslio, short x, short y, short z, short v);
199 void FslGetDim(FSLIO *fslio, short *x, short *y, short *z, short *v);
200 void FslSetDimensionality(FSLIO *fslio, size_t dim);
201 void FslGetDimensionality(FSLIO *fslio, size_t *dim);
202 void FslSetVoxDim(FSLIO *fslio, float x, float y, float z, float tr);
203 void FslGetVoxDim(FSLIO *fslio, float *x, float *y, float *z, float *tr);
204 void FslGetCalMinMax(FSLIO *fslio, float *min, float *max);
205 void FslSetCalMinMax(FSLIO *fslio, float min, float max);
206 void FslGetAuxFile(FSLIO *fslio,char *aux_file);
207 void FslSetAuxFile(FSLIO *fslio,const char *aux_file);
208 void FslSetTimeUnits(FSLIO *fslio, const char *units);
209 void FslGetTimeUnits(FSLIO *fslio, char *units);
210 void FslSetDataType(FSLIO *fslio, short t);
211 size_t FslGetDataType(FSLIO *fslio, short *t);
212 int FslGetIntensityScaling(FSLIO *fslio, float *slope, float *intercept);
213 void FslSetIntent(FSLIO *fslio, short intent_code, float p1, float p2, float p3);
214 short FslGetIntent(FSLIO *fslio, short *intent_code, float *p1, float *p2,
215  float *p3);
216 
217 
218 short FslGetStdXform(FSLIO *fslio, mat44 *stdmat);
219 void FslSetStdXform(FSLIO *fslio, short sform_code, mat44 stdmat);
220 void FslGetMMCoord(mat44 stdmat, float voxx, float voxy, float voxz,
221  float *mmx, float *mmy, float *mmz);
222 
223 void FslGetVoxCoord(mat44 stdmat, float mmx, float mmy, float mmz,
224  float *voxx, float *voxy, float *voxz);
225 short FslGetRigidXform(FSLIO *fslio, mat44 *rigidmat);
226 void FslSetRigidXform(FSLIO *fslio, short qform_code, mat44 rigidmat);
227 int FslGetLeftRightOrder(FSLIO *fslio);
228 
229  /* these two functions are deprecated with the nifti/analyze support */
230  /* please do all spatial coordinate origins via the Std and Rigid Xforms */
231 void FslSetAnalyzeSform(FSLIO *fslio, const short *orig,
232  float dx, float dy, float dz);
233 void FslGetAnalyzeOrigin(FSLIO *fslio, short orig[5]);
234 
235  /* other read and write commands */
236 
237 size_t FslReadSliceSeries(FSLIO *fslio, void *buffer,short slice, size_t nvols);
238 size_t FslReadRowSeries(FSLIO *fslio, void *buffer, short row, short slice, size_t nvols);
239 size_t FslReadTimeSeries(FSLIO *fslio, void *buffer, short xVox, short yVox, short zVox, size_t nvols);
240 
241  /* miscellaneous helper stuff */
242 
243 mat33 mat44_to_mat33(mat44 x);
244 
245 
246 
247 /* added by KF pending discussion w/ Mark */
248 typedef unsigned char THIS_UINT8;
249 typedef char THIS_INT8;
250 typedef unsigned short THIS_UINT16;
251 typedef short THIS_INT16;
252 typedef unsigned int THIS_UINT32;
253 typedef int THIS_INT32;
254 typedef unsigned long THIS_UINT64;
255 typedef long THIS_INT64;
256 typedef float THIS_FLOAT32;
257 typedef double THIS_FLOAT64;
258 
259 FSLIO * FslReadHeader(char *fname);
260 double ****FslGetBufferAsScaledDouble(FSLIO *fslio);
261 double ***FslGetVolumeAsScaledDouble(FSLIO *fslio, int vol);
262 int convertBufferToScaledDouble(double *outbuf, void *inbuf, long len, float slope, float inter, int nifti_datatype ) ;
263 double ****d4matrix(int th, int zh, int yh, int xh);
264 double ***d3matrix(int zh, int yh, int xh);
265 
266 
267 #ifdef __cplusplus
268 }
269 #endif
270 
271 #endif
272 
273 
274 
High level data structure for open datasets in the fslio API.
Definition: fslio.h:123
void FslWriteAllVolumes(FSLIO *fslio, const void *buffer)
Writes all data from buffer (using size info from fslio) to file.
Definition: fslio.c:861
char * FslFileTypeString(int filetype)
Return a string describing the format of the dataset.
Definition: fslio.c:47
Data structures for using nifti1_io API.
double *** d3matrix(int zh, int yh, int xh)
allocate a 3D buffer, use 1 contiguous buffer for the data
Definition: fslio.c:2341
FSLIO * FslInit(void)
allocate space for the FSLIO struct and set some sensible defaults
Definition: fslio.c:370
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: nifti1_io.h:62
Definition: dbh.h:75
void FslWriteHeader(FSLIO *fslio)
Writes nifti/anz header and opens img file ready for writing.
Definition: fslio.c:945
FSLIO * FslOpen(const char *filename, const char *opts)
Opens a file for either reading or writing.
Definition: fslio.c:624
double *** FslGetVolumeAsScaledDouble(FSLIO *fslio, int vol)
Return volume #vol (0-based) as a 3D array of scaled doubles.
Definition: fslio.c:2118
size_t FslWriteVolumes(FSLIO *fslio, const void *buffer, size_t nvols)
Write the first nvols volumes in buffer to disk.
Definition: fslio.c:892
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:1911
FSLIO * FslXOpen(const char *filename, const char *opts, int filetype)
Opens a file for either reading or writing.
Definition: fslio.c:652
Definition: nifti1_io.h:58
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:989
FSLIO * FslReadHeader(char *fname)
Reads nifti/anz header, no data is read.
Definition: fslio.c:2079
double **** d4matrix(int th, int zh, int yh, int xh)
allocate a 4D buffer, use 1 contiguous buffer for the data
Definition: fslio.c:2390
void * FslReadAllVolumes(FSLIO *fslio, char *filename)
Read the header and all data into the FSLIO structure.
Definition: fslio.c:782
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:1046
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:2273
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:1105
size_t FslReadVolumes(FSLIO *fslio, void *buffer, size_t nvols)
Read the first nvols Volumes from a 4D dataset.
Definition: fslio.c:826
Definition: znzlib.h:67
double **** FslGetBufferAsScaledDouble(FSLIO *fslio)
Return the fslio data buffer of a 1-4D dataset as a 4D array of scaled doubles.
Definition: fslio.c:2205