forked from JiadingGai/Impatient-MRI
/
README
777 lines (582 loc) · 37.9 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
(C) Copyright 2010 The Board of Trustees of the University of Illinois.
All rights reserved.
Developed by:
IMPACT & MRFIL Research Groups
University of Illinois, Urbana Champaign
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal with the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimers.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimers in the documentation
and/or other materials provided with the distribution.
Neither the names of the IMPACT Research Group, MRFIL Research Group, the
University of Illinois, nor the names of its contributors may be used to
endorse or promote products derived from this Software without specific
prior written permission.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH
THE SOFTWARE.
------------------------------ Chapter separator ------------------------------
Prolog
------
This is the readme file of the MRI package. This package is contributed by the
IMPACT and MRFIL research groups in University of Illinois at Urbana-Champaign.
------------------------------ Chapter separator ------------------------------
Table of contents
-----------------
1. Introduction
2. Package revision history
3. Environment setup
4. How to compile and run
5. How to integrate it with your project
6. Todo list and future work
------------------------------ Chapter separator ------------------------------
1. Introduction
The MRI toolset is an implementation in CUDA for iterative MR image reconstruction
using Graphics Processing Units (GPUs). It is used in the research of medical ima-
ging, especially in the area of image reconstruction for magnetic resonance imaging
(MRI). In our experiments, this implementation significantly reduces the computation
times by two orders of magnitude (compared with the non-GPU implementation) while
accurately compensating for field inhomogeneity, parallel imaging(SENSE).
For more information about this work, please refer to the following publications.
* Jiading Gai, Joseph L. Holtrop, Xiao-Long Wu, Fan Lam, Maojing Fu, Justin P. Haldar,
Wen-mei W. Hwu, Zhi-Pei Liang, Bradley P. Sutton, More IMPATIENT: A Gridding-Accelerated
Toeplitz-Based Strategy for Non-Cartesian High-Resolution 3D MRI on GPU, Proceedings of
the International Society for Magnetic Resonance in Medicine (ISMRM), May 2012.
* Xiao-Long Wu, Jiading Gai, Fan Lam, Maojing Fu, Justin Haldar, Yue Zhuo, Zhi-Pei
Liang, Wen-Mei Hwu, Bradley Sutton, IMPATIENT MRI: Illinois Massively Parallel Accel-
eration Toolkit for Image reconstruction with ENhanced Throughput in MRI, Proceedings
of the International Society for Magnetic Resonance in Medicine (ISMRM), May 2011.
* Xiao-Long Wu, Jiading Gai, Fan Lam, Maojing Fu, Justin Haldar, Yue Zhuo, Zhi-Pei
Liang, Wen-Mei Hwu, Bradley Sutton, IMPATIENT MRI: Illinois Massively Parallel Accele-
ration Toolkit for Image reconstruction with ENhanced Throughput in MRI, Proceedings
of the IEEE International Symposium on Biomedical Imaging (ISBI), March 2011.
* Xiao-Long Wu, Yue Zhuo, Jiading Gai, Fan Lam, Maojing Fu, Justin P. Haldar, Wen-mei
Hwu, Zhi-Pei Liang, Bradley P. Sutton, "Advanced MRI Reconstruction Toolbox with Accel-
erating on GPU," SPIE 2011.
* Yue Zhuo, Xiao-Long Wu, Justin P. Haldar, Thibault Marin, Wen-mei Hwu, Zhi-Pei Liang,
Bradley P. Sutton, "Using GPUs to Accelerate Advanced MRI Reconstruction with Field
Inhomogeneity Compensation," GPU Computing Gems, Book Chapter 44, Elsevier Inc., 2011.
* Yue Zhuo, Xiao-Long Wu, Justin P. Haldar, Wen-mei Hwu, Zhi-Pei Liang, Bradley P. Sutton,
Multi-GPU Implementation for Iterative MR Image Reconstruction with Field Correction,
Proceeding of International Society for Magnetic Resonance in Medicine (ISMRM) 2010.
* Yue Zhuo, Xiao-Long Wu, Justin P. Haldar, Wen-mei Hwu, Zhi-Pei Liang, Bradley P. Sutton,
Accelerating Iterative Field-Compensated MR Image Reconstruction on GPUs, IEEE Internatio-
nal Symposium on Biomedical Imaging (ISBI) 2010.
------------------------------ Chapter separator ------------------------------
2. Package revision history
Package version : 3.1 alpha
Release date : 03/21/2012
Author list : Jiading Gai, Beckman Institute UIUC (jgai@illinois.edu)
Joseph L. Holtrop, Bioengineering UIUC (holtrop1@illinois.edu)
Xiao-Long Wu, ECE UIUC (xiaolong@illinois.edu)
Fan Lam, ECE UIUC (fanlam1@illinois.edu)
Maojing Fu, ECE UIUC (mfu2@illinois.edu)
Synopsis : The third major release.
New Features :
- Two flags (-writeQ and -reuseQ <path>) have been added to facilitate the
customization of IMPATIENT to specific MRI application, such as fMRI. Recall
that Toeplitz method is perfect for applications such as fmri, where each
slice in every data point shares the same scan trajectory and image s-
ize. A significant portion of the computation in Toeplitz method is the
calculation of Q matrices, which facilitates multiplication operations
involving F^HF and depends only on the scan trajectory (not the scan da-
ta) and the size of the image. Hence, in a task like fmri, Q can be com-
puted once prior to acquiring an image's scan data and re-used on each
slice. In this way, the critical path for a given reconstruction consists
only of compputing F^H(d) and executing the CG solver. Please refer to section 4.3
for more details on the usage of -writeQ and -reuseQ.
Package version : 3.0 alpha
Release date : 03/16/2012
Author list : Jiading Gai, Beckman Institute UIUC (jgai@illinois.edu)
Joseph L. Holtrop, Bioengineering UIUC (holtrop1@illinois.edu)
Xiao-Long Wu, ECE UIUC (xiaolong@illinois.edu)
Fan Lam, ECE UIUC (fanlam1@illinois.edu)
Maojing Fu, ECE UIUC (mfu2@illinois.edu)
Synopsis : The third major release.
New Features :
- In the previous release (2.0 alpha), we implemented a fast image reconstruction routine
for reconstruction of arbitrary 3D imaging trajectories using the Toeplitz computation
structure. In this release (3.0 alpha), we introduce a new IMPATIENT which removes bottlenecks
to the computation by implementing the formation of the Toeplitz operator and formation
of the data input structure in a fast, gridding implementation. Further, we adapt
the algorithm to perform field correction and parallel imaging for large, arbitrary
3D sampling trajectories. Speed-ups of up to a factor of 1000 are provided in the
improved GPU implementation compared to the previous accelerated GPU code.
- 3.0 alpha provides users with three different types of MRI reconstruction strategies.
In reverse chronological order, they are:
2) Toeplitz with gridding:
. Support both 2D and 3D, arbitrary trajectory.
. Fast evaluations of Q (step 1) and FHD (step 2) using gridding algorithm.
. Quickest among the three strategies, but approximate.
-> With a decent gridding oversampling factor, the average
percentage error introduced by gridding is around 1%
. Arbitrary single precision gridding oversampling ratio between [1.0,2.0].
-> It is found that significant reductions in computation memory and
time can be obtained while maintaining high accuracy by using a
minimal oversampling ratio, from 1.125 to 1.375, instead of the
typically employed grid oversampling ratio of two.
. Equipped with various regularization forms:
-> spatial roughness penalty,
-> quadratic regularization
-> total variation.
IMPATIENT 3.0 alpha provides two equivalent ways to implement the regularization
function: 1) sparse matrix ; 2) explicit finite difference calculations.
1) Toeplitz with direct evaluations of $Q$ and $F^HD$:
. Support both 2D and 3D, arbitrary trajectory.
. Direct evaluations of Q (step 1) and FHD (step 2) using their equations.
. slower than Toeplitz with gridding, but as accurate as Brute Force.
-> If Q can be re-used in an MRI experiment on multiple slice, it
can also be much faster than Brute Force
. Equipped with various regularization forms:
-> spatial roughness penalty,
-> quadratic regularization
-> total variation.
IMPATIENT 3.0 alpha provides two equivalent ways to implement the regularization
function: 1) sparse matrix ; 2) explicit finite difference calculations.
0) Brute Force:
. Support only 2D data, arbitrary trajectory.
. Exhaustive evaluation of the entire system equation (both forward and adjoint operators).
. Equipped with various regularization forms:
-> spatial roughness penalty,
-> quadratic regularization
-> total variation.
IMPATIENT 3.0 alpha provides two equivalent ways to implement the regularization
function: 1) sparse matrix ; 2) explicit finite difference calculations.
Package version : 2.0 alpha
Release date : 05/06/2011
Author list : Xiao-Long Wu, ECE UIUC (xiaolong@illinois.edu)
Jiading Gai, Beckman Institute UIUC (jgai@illinois.edu)
Fan Lam, ECE UIUC (fanlam1@illinois.edu)
Maojing Fu, ECE UIUC (mfu2@illinois.edu)
Yue Zhuo, BIOE UIUC (yuezhuo2@illinois.edu)
Synopsis : The second major release.
New Features :
- Toeplitz reconstruction strategy is implemented to provide users with
a choice of the tradeoff between accuracy (Brute Force) and speed (To-
eplitz).
. Takes advantages of Toeplitz formulation for fast computation of sys-
tem matrix computations.
. Field inhomogeneity performed via time segmentation.
. Toeplitz involves approximation, but is also faster. Tradeoff between
number of time segments for accuracy and computation time.
. Toeplitz method is perfect for applications such as fmri, where each
slice in every data point shares the same scan trajectory and image s-
ize. A significant portion of the computation in Toeplitz method is the
calculation of Q matrices, which facilitates multiplication operations
involving F^HF and depends only on the scan trajectory (not the scan da-
ta) and the size of the image. Hence, in a task like fmri, Q can be com-
puted once prior to acquiring an image's scan data and re-used on each
slice. In this way, the critical path for a given reconstruction consists
only of compputing F^H(d) and executing the CG solver.
. More details on Toeplitz: JA Fessler, S Lee, VT Olafsson, HR Shi, DC Noll.
IEEE Trans Sign Proc, 53(9): 3393-3402.
- Toeplitz strategy supports sensitivity Encoding for Fast MRI recon-
struction (SENSE) and total variation (TV) based regularization in our SENSE
framework (solved using an alternating minimization algorithm called half-
quadratic minimization). We provide two ways to encode the regularization matrix
. finite difference (directly calculated on-the-fly).
. compressed row sparse matrix (pre-calculated prior to the recon task).
- Toeplitz method is designed to handle larger image size from 256x256 to
512x512.
- No CPU code is available.
Package version : 1.0 alpha
Release date : 11/19/2010
Author list : Xiao-Long Wu, ECE UIUC (xiaolong@illinois.edu)
Jiading Gai, Beckman Institute UIUC (jgai@illinois.edu)
Fan Lam, ECE UIUC (fanlam1@illinois.edu)
Maojing Fu, ECE UIUC (mfu2@illinois.edu)
Yue Zhuo, BIOE UIUC (yuezhuo2@illinois.edu)
Synopsis : The first major release.
New Features :
- Supports Sensitivity Encoding for Fast MRI reconstruction (SENSE).
- Incorporates a total variation based regularization in our SENSE
framework. (solved using an alternating minimization algorithm called
half-quadratic minimization). We provide two ways to encode the
regularization matrix
. sparse matrix (pre-calculated prior to the recon task).
. finite difference (directly calculated on-the-fly).
- Enable SMVM to increase image quality but some bugs exist.
- FT and IFT are extended to handle larger image size from 256x256 to
512x512. (We have some bugs on 1024x1024 images.)
Package version : 0.1
Release date : 04/16/2010
Author list : Xiao-Long Wu, ECE UIUC (xiaolong@illinois.edu)
Yue Zhuo, BIOE UIUC (yuezhuo2@illinois.edu)
Synopsis : The first release.
Description : Here lists the key functions of this package.
- Use the algorithms mainly referred in the papers, ISMRM 2010 and ISBI
2010.
- Multi-GPU platforms are supported.
- GPU code is modified to accommodate GPU platforms with/out double-
precision hardware.
- CPU code is optimized with OpenMP.
- C++ language is used to facilitate the cooperation with other
projects.
------------------------------ Chapter separator ------------------------------
3. Environment setup
To compile this package you must have the following package installed.
3.1 A Linux-Like Environment
We have successfully tested the package on the following environment.
However, your system shall work if that's not listed below because
we didn't use platform-specific libraries.
- Ubuntu: 9.10, 10.04
- Debian: 4.3.5
- Fedora: 12 13 14
- Mac OS X: 10.06
We haven't tested the package under Windows platforms. But since we
don't use specific libraries for Linux-like platforms, you should be
able to use Windows-based compilers to build the package with/out
minor modifications.
3.2 NVIDIA Graphics Card
We have successfully tested the package with the following cards. Yet,
your graphics card shall work as long as it's supported by the NVIDIA
CUDA.
- Tesla C2050
- GeForce GTX 480
- GeForce GTX 280
- GeForce 8800 GTX
- GeForce 8600M GT
- Quadro FX 5600
3.3 NVIDIA CUDA Developer Driver
After you installed the operating system, the NVIDIA graphics card
device driver should have been installed. If not, you can download the
driver from one of the following links.
Driver version: 260.19.21
http://developer.nvidia.com/object/cuda_3_2_downloads.html
Driver version: 195.36.15
http://developer.nvidia.com/object/cuda_3_0_downloads.html
Driver version: 190.53
http://developer.nvidia.com/object/cuda_2_3_downloads.html
3.4 NVIDIA CUDA Toolkit
CUDA toolkit contains NVCC compiler and the relevant libraries.
You can download the toolkit from one of the following links.
If no special issues, we recommend you to use the latest one.
Toolkit version: 3.2
http://developer.nvidia.com/object/cuda_3_2_downloads.html
Toolkit version: 3.0
http://developer.nvidia.com/object/cuda_3_0_downloads.html
Toolkit version: 2.3
http://developer.nvidia.com/object/cuda_2_3_downloads.html
3.5 Compilers
We have successfully tested the package with the following compiler
versions. It is noted that GCC/++ 4.4 are not supported by NVCC
compilers yet. Besides, if you want to apply OpenMP to parallelize the
CPU code, you must have GCC/++ with version 4.2 or up.
- G++: 3.4, 4.1, 4.3, 4.4
- GCC: 3.4, 4.1, 4.3, 4.4
- CUDA Toolkit: 2.3, 3.0, 3.2, 4.0 RC2
------------------------------ Chapter separator ------------------------------
4. How to compile and run
4.1 Environment setting of the Makefile in the package
After you unzipped the package, please modify the Makefile file to fit
your environment setting and specific requirements for your need.
If you want to have a faster CPU implementation, you can enable OpenMP
to take advantage of the underlying multi-core platform. To enable
OpenMP, you must have GCC/++-4.2 or up and set OPENMP to be "true". The
default is false.
export OPENMP := "false"
To use the double precision computation hardware of your graphics card,
you can set DOUBLE_PRECISION to be "true". GT200 based cards support
double-precision, such as GTX260/275/280/285/295, Telsa C1060, Telsa
S1070, Quadro FX5800 and the new Fermi based cards. The default value
is "false". Note, enabling this variable on the platform not supporting
double precision hardware may cause execution failure.
export DOUBLE_PRECISION := "false"
Besides, please make sure your NVCC compiler is installed under
"/usr/local/cuda". If not, please modify the following variable.
export CUDA_INSTALL_PATH ?= /usr/local/cuda
Finally, you must make sure you provide the right compiler version for
your environment. Note, if your system has two compilers, for example,
GCC/++-4.3 and GCC/++-4.4, you must make sure /usr/bin/gcc and g++
point to the right compiler, GCC/++ version 4.3 in this example. NVCC
seems to use the library of /usr/bin/gcc as the default one during the
compilation without honoring the following variable definitions.
export CXX ?= g++
export CC ?= gcc
export LINKER ?= g++ -fPIC
export AR ?= ar
export RANLIB ?= ranlib
4.2 Compile and make
At the first time, to build the package, please execute the following
command. This shall build all files, including necessary libraries.
$> make clean_all; make CUDA_ARCH=-arch\ sm_xx
Later, if you want to modify some of the source files without
rebuilding all necessary libraries, please execute the following
command.
$> make clean; make CUDA_ARCH=-arch\ sm_xx
To build with more information, you can add "verbose=1" in the command
line, as listed below.
$> make clean verbose=1; make verbose=1 CUDA_ARCH=-arch\ sm_xx
If you modified some macro definitions in any header files, .cuh or .h,
you must "make clean; make" to make sure the changes are propagated to
all source files.
For advanced users who would like to work under debug mode, please use
the following make command.
$> make clean_all debug=1 debug_xcpplib=1;make debug=1 debug_xcpplib=1 CUDA_ARCH=-arch\ sm_xx
Note that, to compile correctly, it is necessary to specify the compute capability
of your GPU card in the Makefile command line (e.g., for a GTX 580, it should be
CUDA_ARCH=-arch\ sm_20; wile for a GTX8800, it should be CUDA_ARCH=-arch\ sm_10).
This is because gridding implementation prefers atomic operation on GPU if available.
4.3 Run the program
This chapter describes the basic usage of the IMPATIENT toolkit. For more
information, please see http://impact.crhc.illinois.edu/mri.php. Before
running the program, you must have data prepared. We provided a handful of
datasets for your reference under the "data" directory.The basic usage of
the IMPATIENT package to reconstruct an image is simple, and it typically
looks something like the following commands:
Example 1: Use the brute force strategy to reconstruct a dataset called
64x64x1 located under data directory.
(a) The number of CG iterations is 8 (by default). Use quadratic
regularization with the weighting parameter lambda set to be
10^-2.
$> ./mriSolver -idir mriData/64x64x1 -fdp 1e-2
(b) The number of CG iterations is 21. Use total variation regularization
with 1) the weighting parameter lambda set to be 10.0 and 2) the num-
ber of TV iteration set to be 16.
$> ./mriSolver -idir mriData/64x64x1 -cg_num 21 -tv -tv_num 16 -fdp 10.0
Example 2: Use the toeplitz strategies to reconstruct a dataset called 32x32x4:
(12 time segments are used to approximate field inhomogeneity)
(a) Toeplitz with gridding is used. The number of CG iterations is 10 (-cg_num). Use total
variation regularization (-tv) with the weighting parameter lambda set to be 10^4 (-tv_num).
The gridding oversampling factor for computing Q is set to 1.125 and the gridding
oversampling factor for computing FHD is set to 1.375 (-gridOS_Q and -gridOS_FH).
Sparse matrix encoded with the finite difference regularization matrix is used (-reg).
to perform the regularization.
$> ./mriSolver -idir mriData/32x32x4 -reg -cg_num 10 -toeplitzGridding \
-tv -tv_num 10 -gpu_id 2 -ntime_segs 8 -fdp 1e4 \
-gridOS_Q 1.125 -gridOS_FH 1.375
(b) To replicate all the parameters and experimental settings in (a).
Only this time, Toeplitz with direct evaluation is used and regularization
is done by explicit finite difference calculations (i.e., without -reg flag).
$> ./mriSolver -idir mriData/32x32x4 -cg_num 10 -toeplitzDirect \
-tv -tv_num 10 -gpu_id 2 -ntime_segs 8 -fdp 1e4
Example 3: To run Toeplitz recon on all the sample data sets and then display
all the sample recons via Matlab. Use the following Bash script:
#!/bin/bash
for file in `ls mriData`; do
export dataDir=mriData/$file;
./mriSolver -idir $dataDir -cg_num 10 -toeplitzGridding -tv -tv_num 10 \
-fdp 1e-6 -ntime_segs 8 -gridOS_Q 1.125 -gridOS_FH 1.375;
done
Also, there are more command options as listed below :
$> ./mriSolver <Options>
Mandatory options:
-idir <dir> MRI input data directory.
Image enhancement options:
-toeplitzDirect Use the toeplitz reconstruction strategy with direct evaluation.
The default reconstruction strategy is brute force.
-toeplitzGridding Use the toeplitz reconstruction strategy with gridding.
The default gridding oversampling factor for Q is 1.125.
The default gridding oversampling factor for FHD is 1.5.
The default reconstruction strategy is brute force.
-gridOS_Q <num> Specify the gridding oversampling factor for Q. <num> has
to be in the range [1.0,2.0]
-gridOS_FH <num> Specify the gridding oversampling factor for FHD. <num> has
to be in the range [1.0,2.0]
-ntime_segs <num> Specify how many time segments to be used by the Toeplitz
reconstruction strategies.
-writeQ This flag will cause the computed Q data structure to be written
to hard disk. This can be useful when a user wants to re-use the saved
Q for reconstruction of later slices, so as to save the time spent
to re-compute the same Q again.
-reuseQ <dir-to-Q> This flag tells IMPATIENT to skip the computation of Q (i.e., step 1).
Instead, a previously saved Q from hard disk will be re-used for
reconstruction of the current slice in the CG step (i.e., step 3).
Note that <dir-to-Q> has to be the path name to the directory that contains
the to-be-reused Q file. The to-be-reused Q file has to bear the filename
'Q_stone.file'
-cg_num <num> Number of iterations for the Conjugate Gradient method.
Default number of iteration is 8.
-reg Enable roughness regularization that incorporates a priori
information to stablize reconstructions when data-consistency
constraints alone do not result in a sufficiently well-posed
inverse problem.
-fd Enable finite difference penalizer. This penalizer denotes the
finite difference of every pixel pair along the horizontal and
vertical directions of the image respectively.
-fdp <num> Specify finite difference penalizer value. WARNING to the users
who would like to use regularization: this weight parameter lambda
is expected to significantly impact your reconstruction quality.
You are forced to choose the value of lambda properly based on your
data and application. IMPATIENT HAS NO DEFAULT VALUE FOR lambda and
NO AUTOMATIC WAY TO SELECT AN OPTIMAL lambda FOR YOU.
-tv Enable total variation regularization that penalizes the total amount
of gradient while preserving the edge information in the image.
-tv_num <num> Number of iterations for the total variation regularization. Default
number of iteration is 10.
-tv_update Enable updates of the outputs for each TV iteration.
Miscellaneous options:
-odir <dir> MRI output data directory. If the output directory is not provided,
"<idir>/output" is used.
-cpu Enable image reconstruction on CPUs as a comparison to the GPU counter-
parts. Default is not enabled. This flag is not applicable to toeplitz
strategy as there is no corresponding cpu code availabe for toeplitz.
-mgpu Enable multiple GPU computatoin when possible. When this option is not
specified, only one GPU is used.
-nogpu Disable the GPU part computation. This enables the CPU computation automatically.
-version Version of this release and the license.
-help View this message.
4.4 Input/Output data and the corresponding formats
Here we list the input/output files and their corresponding information
so that you can feed our program with your data. If you'd like to
modify the program to fit your needs, you can start from the function,
loadInputData(), in "structures.cpp".
MRI conventions in IMPATIENT:
1) k-space is unitless, and should be contained within the window -N/2
to N/2. Take actual k-space trajectory (with units of 1/m) and multiply
by the field of view (in m) to get unitless k-space. Gridding specially
requires this and is part of the preferred Toeplitz pathway. However,
if only brute force or Toeplitz with direct evaluation is used, then the
limit will not be strictly enforced.
2) Field map has a minus sign convention, field map phase term in the forward
signal model is exp(-i*\omega*t).
3) Field map is in units of radians/second. Time is in units of seconds
4.4.1 Inputs data
Each of our input MRI file consists of two parts: a header (in text format) and the
data (in binary format). The header consists of lines in text format of the following
form:
"<keywords> = <value>\n"
A complete list of header keywords, with brief explanations:
- "version":
A version identifier. The newest version number is equal to 0.20000.
- "xDimension"
An integer number denoting the number of columns in the output image.
- "yDimension"
An integer number denoting the number of rows in the output image.
- "zDimension"
An integer number denoting the number of depths in the output image.
- "coil_number"
The number of coils.
- "slice_number"
The number of slices.
- "file_size"
The total number of single precision floating numbers in the data section.
- "Binary_Size" and "Binary:"
The data in the data section may be divided into meaningful pieces, each
of which is labelled by "<Binary_size>=<value>\n" to denote the size (in
floats), then immediately followed by "Binary:" and the actual binary data
for the piece.
The data part of the input file are also written in binary format using the following mode:
- single precision floats with the vector contents.
The size are N pixels in the image space, M k-space samples per coil and P coils.
fm.dat Field map in units of Hertz. Positive sign
convention - (N-by-1)
idata_r.dat Real part of the initial image estiamte (typically
zeros) - (N-by-1)
idata_i.dat Imaginary part of the initial image estiamte
(typically zeros) - (N-by-1)
ix.dat X-coordinates in image space (pixel grid) - (N-by-1)
X-coordinates in terms of field of view, going from
-0.5 to 0.5-delta_x, indicating the proportion of the
field of view for the current spatial position.
iy.dat Y-coordinates in image space (pixel grid) - (N-by-1)
iz.dat Z-coordinates in image space (pixel grid) - (N-by-1)
kdata_i.dat Real part of the k-space data (M*P-by-1)
kdata_r.dat Imaginary part of the k-space data (M*P-by-1)
kx.dat X-coordinate of the k-space trajectory - (M-by-1)
Unitless k-space data format, where k-space typically
runs from -matrix_size/2 to matrix_size/2-1. This is
the k-space locations times the field of view.
ky.dat Y-coordinate of the k-space trajectory - (M-by-1)
kz.dat Z-coordinate of the k-space trajectory - (M-by-1)
mask.dat Image space computation mask - (N-by-1)
t.dat Acquisition time vector in seconds - (M-by-1)
sensi_r.dat Real part of the Coil sensitivity - (N*P-by-1)
sensi_i.dat Imaginary part of the Coil sensitivity - (N*P-by-1)
Note that in the 1.0 alpha release the iz and kz vectors are not used
(only the first element of the vector is used (should be zero). They
will be integrated in a further release.
Note that toeplitz part of the code also generates five intermediate
data files to facilites the computation of Q matrices etc. The five
intermediate files are ixQ.dat, iyQ.dat, izQ.dat and phiR.dat, phiI.dat.
These are computed based on the input files given above and are saved
in the same directory as the input files given above. The five inter-
mediate files are managed by the internal implementation and should be
irrelevant to end users.
4.4.2 Output data
(a) Brute Force strategy:
Files are written in binary format using the following mode:
- single precision floats with the vector contents.
output_cpu_i.dat Real part of the reconstructed image using CPU -
(N-by-1)
output_cpu_r.dat Imaginary part of the reconstructed image using
CPU - (N-by-1)
output_gpu_i.dat Real part of the reconstructed image using GPU -
(N-by-1)
output_gpu_r.dat Imaginary part of the reconstructed image using
GPU - (N-by-1)
(b) Both Toeplitz strategies:
The single output file named out.file is written in binary format
in the input data directory using the following mode:
- single precision floats
- out.file starts with real part of the reconstructed image and
concludes with imaginary part the reconstructed image.
- one possible Matlab script to display the reconstructed image:
fp=fopen('out.file','r');
recon = fread(fp,'single');
len = length(recon);
recon_r = recon(1:len/2);
recon_i = recon(len/2+1:end);
N = (len/2) ^ 0.5;
gpu_output = reshape(recon_r+1i*recon_i,[N,N]);
figure;
imagesc(abs(gpu_output));
colormap(gray);
Note that two sample Matlab scripts have been provided to display the
two output formats. They reside in the mriSolver directory:
- display_recon.m (Toeplitz)
e.g., MATLAB >> display_recon('mriData/64x64x1/out.file')
- display_recon2.m (Brute Force)
e.g., MATLAB >> display_recon2('mriData/64x64x1/')
4.5 Two more tutorials including code samples in the code package
The IMPATIENT package provides two code demonstrations under
matlab_utils/
to help you get started on the path of reconstructing your own data
with IMPATIENT.
4.5.1 matlab_utils/create_sparse_matrix
This folder contains the Matlab scripts that are used to generate
the regularization sparse matrices (i.e., those c.rmtx files in each
data sub-directory, residing along with other input *.dat files).
The sparse matrices are first generated in memory using Matlab script
createDWithPeriodicBoundary.m, then written to hard disk via mmwrite.m.
c.rmtx is a format invented by Matrix Market. For more details, please
refer to the README file under that directory.
4.5.2 matlab_utils/format_conversion
This folder demonstrates an example of converting into IMPATIENT data format,
an MRI data stored in Matlab's mat file (i.e., recon_data_32x32x4.mat).
Hopefully, this example will save our users' the pain to figure out the hard
way how to convert their favorite MRI data format into the IMPATIENT's format.
For more details, please refer to the README file under that directory.
------------------------------ Chapter separator ------------------------------
5. How to integrate it with your project
The main function in the file, main.cpp, is designed as an example for your
reference. The following code segment is the launch point.
result = mainMriSolver(input_dir, output_dir, iter_num, ...);
if (result == false) {
cerr<< "Error: Failed to execute the "<< prog<< ".\n";
goto _ERROR_mri_main;
}
------------------------------ Chapter separator ------------------------------
6. Todo list and future work
This section lists our ongoing tasks and future work.
Ongoing tasks:
- Further optimize the performance (e.g., thread coarsening).
- Improve the multi-gpu job dispatch queue and distribute the per-coil
computation across many GPUs.
- Extend the gridding kernels to a tiled implementation so that gridding
can be done on larger data sets, whose size would not fit in GPU at once.
- Thorough comparison with existing methods (e.g., NUFFT)
Future work:
- Automatically detect the underlying GPU hardware capability and
choose the right parameters.
------------------------------ End of README File -----------------------------