Numerical MRI simulation can dramatically speed the understanding and development of new MR imaging methods. In this work, a new simulation package named ’MRiLab’ has been invented for performing fast 3D parallel MRI numerical simulation on regular desktop computer. This simulation package is aimed to provide a fast, comprehensive and effective numerical MRI simulation solution with minimum computing hardware requirement.
This manual is aimed to provide a comprehensive introduction to various functions included in MRiLab package, through demonstrating a workflow of simulation, dedicated toolboxes and built-in libraries capable of customizing various aspects of MR simulation experiment. You should become familiar and comfortable with all the design functions available in MRiLab after reading this User Guide.
It’s my greatest pleasure to know that MRiLab can help you in your MR research and/or education. Please don’t hesitate to leave me feedback about any aspect of MRiLab and/or about this User Guide. All the effects for improving MRiLab will hopefully help MR researchers including myself for better understanding and improving future MR techniques.
The MRiLab is a numerical MRI simulation package. It has been invented and developed to simulate MR signal formation, k-space acquisition and MR image reconstruction. MRiLab provides several dedicated toolboxes for MR researchers to analyze RF pulse, design MR sequence, configure multiple transmitting and receiving coils, investigate field inhomogeneity and test real-time imaging technique etc. The main MRiLab simulation platform combined with these toolboxes can be applied for customizing various virtual MR experiments which can serve as a prior stage for prototyping and testing new MR technique and application.
The MRiLab features highly interactive graphical user interface (GUI) for the ease of fast experiment design and technique prototyping. A high simulation accuracy is achieved by simulating discrete spin evolution at small time interval using the Bloch-equation and appropriate spin model. In order to manipulate large multidimensional spin array, MRiLab employs parallel computing by incorporating latest GPU technique and multi-threading CPU technique. Benefit from the accelerated computing, MRiLab can accomplish multidimensional multiple spin species MR simulation with high simulation accuracy and time efficiency, and with low computing hardware cost.
The current MRiLab version (v1.2) is made available at SourceForge website.
MRiLab is released as a free software. This means that you are free to use and
modify this software as your needs, as long as you acknowledge the original author in
any future work. If you find MRiLab useful for the publication of any scientific
results, including a line in your acknowledgments section referencing to MRiLab and
this belowing address is requested.
MRiLab downloading address:
To run MRiLab, a Matlab installment is required. The current MRiLab version has been tested under the following Matlab versions:
Installing and running MRiLab is easy, you just need to download MRiLab source
code which is distributed as a compressed file, then extract the MRiLab root
folder, put the folder to any location in you computer. To run MRiLab, start
Matlab, then simply run the ‘MRiLab.m’ script under the MRiLab root folder.
The graphical user interface in MRiLab is developed under Matlab GUIDE
environment. Most of the simulation configuration code is programmed using
pure Matlab language and Extensible Markup Language (XML), however,
the computation intensive functions are programmed and optimized using
MATLAB Executable (MEX) C code. These MEX binaries includes all the
computing kernels that interact with GPU device via NVIDIA CUDA and
with multi-core CPU via OpenMP. Some three-dimensional image rendering
functions are also programmed using Visualization Toolkit (VTK) and compiled
into MEX. These MEX binary library files have been built under 64-bit
Windows and Linux OS system and shipped with MRiLab source code, so
the user should be able to use these files under 64-bit Windows and Linux
without the need of recompiling. However, if these MEX files are incompatible
with your OS system for any reason or if you wish to modify these MEX
files for your own needs, you have to recompile them using the source code.
Before recompiling these MEX files, some dependent packages are required.
Intel IPP : http://software.intel.com/en-us/intel-ipp
AMD Framewave : http://framewave.sourceforge.net
NVIDIA : http://www.nvidia.com/page/home.html
CUDA : http://www.nvidia.com/object/cuda_home_new.html
Although the GPU acceleration dramatically improves computational efficiency for MRiLab, the GPU computing mode is also optional. Alternatively, MRiLab provides multi-threading CPU computing mode via OpenMP which requires no additional packages on most of today’s operating system, but provides comparable computational efficiency compared to GPU mode.
VTK : http://www.vtk.org
ISMRMRD : http://ismrmrd.sourceforge.net/#obtaining-and-installing
After installing above mentioned necessary dependent packages, you also need to set a few environment variables in your system :
Notice that the C source code for these MEX files is under /MRiLab/Lib/src folder. To compile and install MEX files
You can also use cmake-gui for configuration and other building tools (e.g. Eclipse) for building the binaries.
If installation problems do occur to you, feel free to let me know and I may help you out. For your information, I provide here my development environment (Table 1.1) for the current MRiLab version.
| Environment | Desktop | Laptop |
| Machine | Dell Precision T3500 | Lenovo Thinkpad R61 |
| CPU | Intel Xeon W3530 | Intel Core2 Duo T8100 |
| GPU | NVIDIA Quadro 4000 | Null |
| OS | Windows 7 64-bit | Linux Fedora 16 64-bit |
| Matlab | Matlab R2013a 64-bit | Matlab R2012b 64-bit |
| C Compiler | Visual Studio 10 Win64 | GCC 4.6.3 |
| VTK | VTK 5.10 | VTK 5.10 |
| CUDA | CUDA 5.0 | Null |
| IPP | Intel IPP 7.0 | Intel IPP 7.0 |
| Framewave | AMD Framewave 1.3 | AMD Framewave 1.3 |
The MRiLab simulation platform consists of
MRiLab applies XML files for storing simulation information, which simplifies simulation experiment modification across different studies. MRiLab also supports external plugins programmed using either Matlab or C language for creating extendable simulation system.
The workflow diagram of MRiLab simulation is shown in Figure 2.4. One typical simulation requires input of :
All the input information gets configured at the MRiLab main control console where the user can customize any aspect of a simulation experiment. The main console preprocesses the input information then translates them into kernel signal, based on which the discrete solving kernel executes each voxel of imaging objects with either GPU or multi-threading CPU acceleration. The acquired MR signal and k-space data from the kernel then passes to image reconstruction module where either default recon code or external recon tool (e.g. Gadgetron) is applied. The reconstructed image can be analyzed using MRiLab image display tools including :
Up to this point, you may wonder how I can start to use MRiLab for imaging simulation. Below is a simple 3D Gradient Echo (GRE) simulation example for you to gain some feelings of using MRiLab.
The final looks of this 3D GRE experiment should be somewhat similar to this (Figure 2.5).
If you managed to simulate this gradient echo image, congratulations! You have successfully performed your first MRiLab experiment. So you should be prepared for deeper understanding of MRiLab simulation platform by following the rest of this user guide.
Prior to performing any type of simulation in MRiLab, a virtual object has to be
loaded first. There are three ways of loading a virtual object: go to menu ‘Load’ and
‘Load Phantom’ to load a user customized phantom in .mat file; go to ‘Load
Phantom Example’ to load MRiLab default phantoms with MR properties mimicking
several human tissue types (e.g. Brain, Cartilage, Fat, etc.); go to ‘Load Phantom
from XML’ to load a phantom that are configured using a phantom XML file
(Chapter 5.3). Note that in the third loading method, a VObj XML file needs to be
selected through ‘Load Phantom XML’ prior to loading phantom (note default
phantom XML files are saved under the MRiLab phantom XML root folder /VObj ).
Once a virtual object being successfully loaded, the geometry of this phantom will show as a preview thumbnail at the top right corner of the console (Figure 3.1). The user can inspect the middle slice of the phantom property maps of T1, T2 and Rho etc. using the pop-up menu above the thumbnail. To inspect all slices, the user can click ‘Display’ button to open an individual display window from MatrixUser. If multiple spin species exist in the phantom, the user can also inspect different spin type by using ‘Spin Type’ pop-up menu below the thumbnail. Moreover, a complete list of phantom property of the virtual object is provided at the ‘Virtual Object Property’ list, the user can check any of them by clicking the corresponding item. A complete property list of one virtual object typically include:
To inspect more details of the digital phantom, press the ‘Localizer’ button to populate the thumbnail to the main image display panel. MRiLab provides three image axes to display axial, sagittal and coronal view section of the three dimensional virtual object, respectively. A scroll bar beside each axes allows to change image slice along the corresponding direction, which serves as an anatomical reference for prescribing simulation parameters. For instance, the location of a green box in each axes indicating current field of view can be adjusted via free hand dragging, and the field of view location is instantly updated at ‘Field of View’ panel upon dragging.
One of the key features of MRiLab is allowing simulating a wide range of MR sequences and facilitating investigation and optimization of desirable MR contrast among different tissues. MRiLab provides a sequence loading interface allowing users to choose predefined sequences from default MRiLab sequence library, or choose other user customized sequences. MRiLab parses a selected MR sequence and translates the sequence waveform into specific signal which triggers simulation kernel execution. The sequence loading interface provides functions to load MR sequence. A MR sequence design toolbox is separate from loading interface and will be explained in detail in Chapter 5.
To open a sequence loading interface (Figure 3.2), click the ‘Sequence’ button
located at the center portion of the main control console. Once the interface is open,
the ‘Dimension’ specifies the sequence spatial encoding scheme (2D or 3D). The
‘Category’ provides a list of sequence classes including Gradient Echo, Spin Echo,
Inversion Recovery, Fast Spin Echo, Others and User. Upon clicking one sequence
category, a few sequences belonging to the selected category become available in the
sequence list on the right. Click a sequence, then press ‘Accept’ to load the selected
sequence. pressing ‘Cancel’ button will close the interface without loading any
sequence.
Notice there is a ‘Special Technique (SpecialTech)’ panel below the sequence list.
If a sequence using any of special techniques is selected, the corresponding
checkboxes beside the special techniques will be chosen. For example, by default
PSD_FIESTA3D uses the special techniques called DummyPulse, therefore, by
clicking PSD_FIESTA3D, the DummyPulse will be chosen accordingly. However, you
can uncheck the checkbox for avoiding the DummyPulse module, but this may cause
incomplete simulation for PSD_FIESTA3D. It is recommended to keep default
selection of special techniques therefore a complete sequence control is preserved for
those default sequences. On the other hand, for the sequences that have no special
techniques, you can also add special technique module by checking corresponding
checkbox. This will load parameter tabs of special techniques on the simulation
control console for configuration purpose. The special technique strategy
enables the ability for reusing ‘capsulized’ module for different sequences.
MRiLab provides a few default sequences under the folder /PSD, notice the /PSD folder uses the same hierarchic structure scheme as that of the loading interface. Typically a new sequence can be located anywhere in the computer, however it is recommended to save the sequence under those predefined categories under /PSD therefore they are visible to the loading interface. However, if a customized sequence is not directly visible to the loading interface, it can also be loaded using the PSD loading button marked as ‘o’ at the bottom of the loading interface. If the PSD loading button is used, loading interface will ignore regular sequence selection.
MRiLab provides a few predefined MR sequences including
To simulate multi-transmitting and receiving coil, MRiLab provides a coil loading interface allowing to choose different coil configurations for Tx (i.e. Transmitting) and/or Rx (i.e. Receiving). MRiLab translates the coil configuration and computes a B1+/B1- field accordingly. For multi-transmitting coil, each coil element could be treated separately and receives individual RF signal source. This allows to investigate B1 shimming and multiple RF excitation etc. For multi-receiving coil, each coil element also connects to an individual signal channel and produces signal according to its specific coil sensitivity. This allows to investigate coil encoding methods such as parallel imaging. The coil loading interface provides functions to load coil configuration. A coil design toolbox is separate from loading interface and will be explained in detail in Chapter 5.
To open a coil loading interface (Figure 3.3), click the ‘Coil’ button located at the
center portion of the console. The ‘Category’ list specifies different coil configuration
category based on anatomical structure. The ‘Coils’ list beside the ‘Category’ list
provides coil configuration belonging to the selected category. Upon clicking a coil
configuration, the interface will calculate the coil sensitivity map and display it in the
preview axes. The user can specify displaying spatial resolution using the ‘Precision’
with a highest spatial resolution defined as the same resolution of digital phantom.
Moreover, the user can specify color map from ‘Jet’,‘Gray’ or ‘Hot’. Pressing ‘Accept’
will load the selected coil configuration. However, pressing ‘Cancel’ button will
close the interface without loading any coil configuration. If an uniform unit
coil sensitivity is desired, press ‘Uniform’ button to load that. By default,
MRiLab uses an uniform unit coil sensitivity for both RF transmitting and
receiving. To indicate an usage of the selected coil configuration, the user has
to specify ‘Coil Type’ as either Tx for transmitting or Rx for receiving.
MRiLab provides a few default coil configuration under the folder /Coil, notice the /Coil folder uses the same hierarchic structure scheme as that of the loading interface. Typically a new coil configuration can be located anywhere in the computer, however it is recommended to save the coil configuration folder under those predefined categories under /Coil therefore they are visible to the loading interface. However, if a customized coil configuration is not directly visible to the loading interface, it can also be loaded using the Coil loading button marked as ‘o’ at the bottom of the loading interface. If the Coil loading button is used, loading interface will ignore regular coil selection.
MRiLab provides a few predefined coil configuration including
MR simulation studies may need to use non-uniform magnetic field. Those studies include the ones for investigating susceptibility artifact, and developing less field inhomogeneity sensitive sequences. MRiLab provides the magnet loading interface allowing to load customized B0 field inhomogeneity map (i.e. dB0 map, a map for indicating main field variation). The magnet loading interface provides functions to load dB0 map. A magnet design toolbox is separate from loading interface and will be explained in detail in Chapter 5.
To open a magnet loading interface (Figure 3.4), click the ‘Magnet’ button
located at the center portion of the console. The ‘Category’ list specifies different
magnet category based on anatomical structure. The ‘Magnet’ list beside the
‘Category’ list provides magnet belonging to the selected category. Upon clicking a
magnet file, the interface will compute a dB0 map and display it in the preview axes.
Pressing ‘Accept’ will load the chosen magnet profile. However, pressing
‘Cancel’ button will close the interface without loading any profile. If an
uniform B0 field (i.e. zero dB0) is desired, press ‘Uniform’ button to load
that. By default, MRiLab uses an uniform B0 field for simulation. That
is to say there is no field inhomogeneity across the entire virtual object.
MRiLab provides a few default magnet profile under the folder /Mag, notice the /Mag folder uses the same hierarchic structure scheme as that of the loading interface. Typically a new magnet profile can be located anywhere in the computer, however it is recommended to save the magnet profile folder under those predefined categories under /Mag therefore they are visible to the loading interface. However, if a customized magnet is not directly visible to the loading interface, it can also be loaded using the Magnet loading button marked as ‘o’ at the bottom of the loading interface. If the loading button is used, loading interface will ignore regular magnet selection.
MRiLab provides two predefined magnet configuration including
Regular MR spatial encoding is performed in a linear (flat) fashion. However encoding in a nonlinear (curved) fashion may serve particular purposes in some MR studies. MRiLab provides a gradient loading interface to load customized 3D nonlinear gradient field. This function can help investigate arbitrary curved gradient field for imaging simulation. Benefit from MRiLab’s powerful functionality of MR sequence design, nonlinear gradient encoding techniques such as PatLoc can be simulated with minimal efforts in MRiLab. The gradient loading interface provides functions to load nonlinear gradient. A gradient design toolbox is separate from the loading interface and will be explained in detail in Chapter 5.
To open a gradient loading interface (Figure 3.5), click the ‘Gradient’ button
located at the center portion of the console. The ‘Category’ list specifies different
gradient category based on the anatomical structure. The ‘Gradient’ list beside the
‘Category’ list provides gradient profile belonging to the selected category. Upon
clicking a gradient configuration, pressing ‘Accept’ will load the selected gradient
profile. However, pressing ‘Cancel’ button will close the interface without loading
any gradient profile. If a constant unit gradient is desired, press ‘Constant
Unit’ button to load that. By default, MRiLab uses a constant unit gradient
profile in the X, Y and Z direction for a typical gradient simulation. This will
maintain a conventional linear spatial encoding in all three spatial dimensions.
MRiLab provides gradient profiles under the folder /Grad, notice the /Grad folder uses the same hierarchic structure scheme as that of the loading interface. Typically a new gradient profile can be located anywhere in the computer, however it is recommended to save the gradient profile under those predefined categories under /Grad therefore they are visible to the loading interface. However, if a customized gradient is not directly visible to the loading interface, it can also be loaded using the Gradient loading button marked as ‘o’ at the bottom of the loading interface. If the Gradient loading button is used, loading interface will ignore regular gradient selection.
MRiLab provides one predefined example of gradient profile
MRiLab provides a motion simulation mechanism which implements simulating imaging object movement in three dimensional space. MRiLab’s Motion simulation introduces an approach for simulating four dimensional imaging (3D space + time) techniques such as k-t blast and enables developing real time image reconstruction algorithms. It also helps investigate motion insensitive sequence and test motion artifact in various types of sequences and conditions. The motion loading interface provides functions to load motion trajectory. A motion design toolbox is separate from the loading interface and will be used for designing motion pattern in three dimensional space.
To open a motion loading interface (Figure 3.6), click the ‘Motion’ button located
at the center portion of the console. The ‘Category’ list specifies different motion
category based on the anatomical structure. The ‘Motion’ list beside the ‘Category’
list provides motion profile belonging to the selected category. Upon clicking a
motion pattern, pressing ‘Accept’ will load the chosen motion profile. However,
pressing ‘Cancel’ button will close the interface without loading any motion profile. If
motion isn’t desirable, press ‘Stationary’ button. By default, no motion is used in
MRiLab simulation.
MRiLab provides motion profiles under the folder /Mot, notice the /Mot folder uses the same hierarchic structure scheme as that of the loading interface. Typically a new motion profile can be located anywhere in the computer, however it is recommended to save the motion profile under those predefined categories under /Mot therefore they are visible to the loading interface. However, if a customized motion is not directly visible to the loading interface, it can also be loaded using the Motion loading button marked as ‘o’ at the bottom of the loading interface. If the Motion loading button is used, loading interface will ignore regular motion selection.
MRiLab provides two predefined examples of motion profile
Those loading interfaces offer a mechanism to interpret and convert configuration file into MRiLab parameters. With a successful loading, the ‘Coil Selection’, ‘Magnet Selection’,‘Gradient Selection’ and ‘Motion Selection’ fields indicate the current selected configuration. The user can change the configuration by reloading a new configuration file with above mentioned steps. If any of these fields are empty, a default setting will be used. Similar to a real scanner system, MRiLab categorizes scanning parameters into different groups and present them under different tabs in the ‘Simulation Settings’ panel (Figure 3.7). There are five tabs which are included in all MR sequences, including Imaging, Advanced, Hardware, Recon and CVs. Additional tabs for special techniques will also become valid if those techniques are loaded from sequence selection. Below are detailed explanation for each of those parameters.
Below are a full list of supported simulation parameters in current MRiLab version. Notice that unless otherwise specified, MRiLab uses International System of Units (i.e. SI units) for all the parameters.
The ‘Imaging’ tab contains parameters relevant to image resolution, field of view and timing setting etc.
The ‘Advanced’ tab contains other imaging parameters.
The ‘Hardware’ tab contains parameters relevant to system hardware setup.
The ‘Recon’ tab contains parameters relevant to image reconstruction.
The ‘CVs’ tab contains Controllable Variables (CV) which exist in the global scope of sequence design. They are designed for conveniently transferring values among multiple MR sequence modules. The user can use them for customized purpose.
The Special Technique (SpecialTech) contains multiple tabs from which one or more are loaded based on sequence configuration and user choice.
The current MRiLab version supports two types of parallel computing mechanisms: GPU based parallel computing using CUDA and multi-threading CPU based parallel computing using OpenMP. As mentioned before, the GPU support requires NVIDIA GPU with CUDA capability (shader model 2.0) along with properly installed GPU driver. The OpenMP is, on the other hand, supported by most of modern multi core CPU. If both GPU and CPU are available in user’s system, the user can choose to use any of these two methods. To switch parallel computing methods, go to ‘Parallel’ menu and ‘Select Engine’ and choose available GPU or CPU devices.
The MRiLab converts simulation parameters from configuration files into temporary
configuration structures during loading process, and uses these structures to organize
simulation workflow. The user can check the default value of each parameter by
moving a mouse cursor on top of selected parameters. The use can adjust
loaded simulation parameters to satisfy a simulation design, to make changing
parameters effective, the user has to press ‘Update’ button located below
‘Simulation Settings’ panel. The ‘Update’ button not only updates these
structures, but also performs a series of pre-scan processes including checking
incompatibility error and initializing other necessary simulation variables.
On the left of ‘Update’ button, there is a ‘Save’ button which saves updated
configuration structure back into corresponding configuration files for later use. One
particular case is that ‘CVs’ need to be updated and then saved in order to make
changes effective. This is because ‘CVs’ is one part of the sequence file which needs to
be interpreted at the sequence waveform generation module. The sequence memo is
also provided at the ‘PSD Memo’ panel. It’s editable and can be saved using ‘Save’
button.
On the right of ‘Update’ button, there is a ‘Scan’ button which activates sequence waveform generation, actual scan process and post-scan process including image reconstruction and data saving. The MRiLab automatically detects any parameter changes and set ‘Scan’ button disabled. To enable ‘Scan’ button, simply press ‘Update’ button. Notice that the update process may take some time if a large number of initialization is needed, so be patient and wait it to finish before proceeding. The ‘Simulation Info Log’ is helpful for checking log information about each simulation step. Once simulation setting gets configured properly, the user can press ‘Scan’ button to start scanning.
Figure 4.1 demonstrates an example of a series of simulation operated with different sequences. Each sequence is labeled with an unique series number, and shows in the list at ‘Scan Series’ panel. This series number is also a reference for the saved image and data in the output database which will be explained in Chapter 5. There is also a status label on the left of each sequence name. The status labels include:
The example shows a series of successful simulation by using PSD_GRE3D, PSD_GRE3DRadial and PSD_FIESTA3D sequences, but incomplete simulation using PSD_FIESTA3D at the second time. The preview axes displays an image preview for the series 2 simulated using PSD_GRE3DRadial sequence. The user can switch previews for successful simulation by clicking scan series item. Moreover, the series name is also editable although in this example the series name is kept the same as the name of the sequence, which is not absolutely necessary. If the multiple channel coil for multiple receiving is performed (Figure 4.2), the user can specify display image to any channel with ‘Channel #’ pop-up menu, or choose ‘SumofMagn’ for summation of image magnitude of all channels or ‘SumofCplx’ for summation of complex image of all channels. If multiple echo is enabled in the sequence, the user can also specify display image to any echo with ‘Echo #’ pop-up menu. Default value of 1 is used for single echo. The preview image provides a quick overview of the simulated images, a further image analysis can be performed with image display and analysis tools in Chapter 6.
At the bottom of the preview axes, there are information for the name of currently running sequence, estimated remaining scan time in real time and a scan progress bar. A global relative SNR and SAR (:TODO) are also provided and automatic updated in real time. The relative SNR is defined as the ratio of current SNR to the initial SNR calculated upon loading the sequence. The SNR value is calculated using Equation 4.1.
 | (4.1) |
where
 | (4.2) |
In order to simulate image noise, MRiLab performs a noise adding process in k-space after signal acquisition. The Gaussian noise with zero mean and user-defined standard deviation is added to the complex signal. The standard deviation is determined using Equation 4.3. If no noise is desired, the user can set ‘NoiseLevel’ to zero to get infinite SNR.
 | (4.3) |
where these reference values are given as:
 | (4.4) |
MRiLab toolboxes consists of several individual graphical user interfaces for conducting RF pulse design, MR sequence design and Coil design etc. These toolboxes allow users to fast and effectively build and customize their own specific MR simulation experiment. This chapter covers the introduction to each toolbox and corresponding macro libraries.
The RF pulse design toolbox can be activated by pressing ‘RF Design Panel’ toolbar icon located at the top of the main simulation console.
Figure 5.2 demonstrates an overview of the RF Pulse Design interface. This interface consists of
The user can use this interface to analyze tissue spin response regarding a selected RF and gradient pulse. To select a RF pulse macro, the user needs to click the macro library tree to unfold the tree structure, and then click a desired RF macro. The properties of the chosen RF macro will show on the left panel under ‘rf:rf name’ tab. The RF memo information is also shown at the ‘rf Memo’ panel below the tree structure. The user can press ‘Execute’ button to start analysis process. MRiLab supports three analysis modes for analyzing 1D spatial RF pulse, 2D spatial RF pulse and Spatial-Spectral RF pulse:
MRiLab assumes a gradient is applied in the Z direction, therefore a constant gradient will be applied if ‘Gz’ tab is empty (Figure 5.3). To select a ‘Gz’ gradient, the user needs to choose a gradient macro under ‘GzSS’. For example, the ‘GzSelective’ is a recommended gradient macro typically used for performing slice selection in MRiLab. Once the user selected a gradient macro, the ‘Gz:gradient name’ tab will become activated and the properties of this gradient macro become accessible and editable. The user can modify macro attributes to meet design goals. To make any modification effective, the user must press ‘Update’ button before executing the slice profile analysis. Although the library tree contains macros for another gradient line (e.g. GyPE, GxR), they are typically ignored in this mode.
MRiLab assumes a gradient is applied in both the X and Y directions, a constant gradient will be applied if ‘Gx’ tab or ‘Gy’ tab is empty. The user can choose any Gx and Gy gradient macros for these two tabs and modify macro attributes to satisfy 2D rf pulse design. To activate 2D pulse analysis, the ‘Spat_Flag’ under ‘XSpatial’ tab has to be turned on (4c). The Gz gradient is typically ignored under this mode.
MRiLab assumes a gradient is applied in the Z direction, a constant gradient will be applied if ‘Gz’ tab is empty. The user can choose any Gz gradient macros for this tab and modify macro attributes to satisfy Spatial-Spectral pulse design. The user can also modify the frequency range and resolution under ‘Spectral’ tab (4e). To activate Spatial-Spectral pulse analysis, the ‘Freq_Flag’ has to be turned on (4e). The Gx and Gy gradient are typically ignored under this mode.
Under 1D Spatial Mode, MRiLab provides three slice profile figures (Figure 5.4) on the ‘Spin Response’ panel under different tabs. These figures include slice profile regarding
The horizontal axis is the spin position in units of meters, and the vertical axis is the value of the components in normalized units.
Under 2D Spatial or Spatial-Spectral Mode, MRiLab provides another five spin response figures on the ‘Spin Response’ panel under different tabs. These figures include
The horizontal axis is the spin position for 2D Spatial mode and the frequency range for Spatial-Spectral mode, and the vertical axis is the spin location in both mode. Notice the units of both axes use spin index for either spatial position or frequency position according to spin property and environment (4c, 4d and 4e).
MRiLab also plots the RF and gradient waveform. In MRiLab, the property of a RF pulse contains RF amplitude (T), RF phase (rad) and RF frequency (Hz). The RF frequency is defined as the spin Larmor frequency minus the laboratory frequency of the RF pulse. Notice that in those figures, for display purpose, the gradient amplitude is in units of G/cm and RF amplitude is in units of G. Both time axes are in units of milliseconds. At the bottom of this interface, there is a group of pushbuttons (Figure 5.5) allowing the user to investigate intermediate spin response during a applied RF and gradient (Figure 5.6).
MRiLab renders three-dimensional spin response in ‘3D Spin Response’ panel based on different modes. The user can inspect the behavior of spins at specific location under a chosen RF pulse and gradient. The user can use Matlab default graphical tools for interactively changing display view and size (Figure 5.8). To change three-dimensional spin response content reflecting different tabs in 2D spatial mode or Spatial-Spectral model (Figure 5.7), the trick is to simply activate any item of the playback control group (e.g. click the scroll bar).
The user can modify the spin properties and environment to satisfy their experiment design. The editable properties provided in this interface include:
Figure 5.9 demonstrates a slice profile for two different spin species under the same RF pulse and gradient in 1D spatial mode. To enable slice profile analysis for multiple spin species, the user needs to provide multiple values for T1, T2, Rho and ChemShift in an array, and give the correct number of spin species. The values must be separated with space. For example
MRiLab uses a concept of macros for simplifying experiment design. A RF macro is a predefined module for a RF pulse with the features of programming-free and flexible of modification for specific experimental design using the RF Design interface. MRiLab RF macro library is a collection of RF macros covering from simple RF pulses such as hard pulse, to complex RF pulses such as adiabatic pulses. A specific RF macro to interact with external RF pulse file is also provided to create more extensible pulse design environment. This section will give an introduction to each of the RF macros provided in MRiLab.
A RF macro that creates a Sinc type RF pulse. This macro contains attributes including:
The time dependence of the Sinc RF pulse is given by [6]:
 | (5.1) |
where A is the peak RF amplitude automatically calculated and scaled according to flip angle, t0 is one-half the width of the central lobe, and the NL and NR are the number of zero-crossings to the left and right of the central peak, respectively. In MRiLab, the NL ≡ NR, thus the Sinc RF pulse is always symmetric. Notice that the The time bandwidth product of a Sinc pulse equals the number of zero-crossings including the start and end. In order to address the discontinuity at the start and end, apodization can be applied using ‘Hamming’ or ‘Hanning’ window as described by:
 | (5.2) |
where N equals NL and NR. Hamming window uses α = 0.46, and Hanning window uses α = 0.5. If ‘Non’ is used, apodization is disabled.
A RF macro that creates a hard RF pulse. This macro contains attributes including:
The time dependence of the hard RF pulse is given by [6]:
 | (5.3) |
where A is the peak RF amplitude automatically calculated and scaled according to flip angle, T is the width of RF pulse that equals tEnd-tStart.
A RF macro that creates a Gaussian type RF pulse. This macro contains attributes including:
The time dependence of the Gaussian RF pulse is given by [6]:
 | (5.4) |
where A is the peak RF amplitude automatically calculated and scaled according to flip angle, σ is linearly proportional to the pulse width. Also the Gaussian RF pulse is terminated with a 60-dB attenuation.
A RF macro that creates a Fermi RF pulse. This macro contains attributes including:
The time dependence of the Fermi RF pulse is given by [6]:
 | (5.5) |
where A is the peak RF amplitude automatically calculated and scaled according to flip angle, t0 is a measure of the pulse width that corresponds to PW, α is a measure of the transition width. The Fermi pulse approximates more to a rectangle pulse with larger t0 value. Also the Fermi RF pulse is terminated with a 60-dB attenuation.
A RF macro that creates a RF pulse using Shinnar-Le Roux algorithm. This macro contains attributes including:
MRiLab implements a library of Matlab SLR pulse design routines that is originally developed by Prof. John Pauly and published online at http://rsl.stanford.edu/research/software.html. Thorough explanation of the algorithm is beyond the scope of this manual, users who are interested in the SLR algorithm are referred to [6, 7].
A RF macro that creates an adiabatic inversion RF pulse based on hyperbolic secant modulation. This macro contains attributes including:
The time dependence of the hyperbolic secant RF pulse is given by [6]:
 | (5.6) |
where A0 is the maximum B1 field corresponding to MaxB1, μ is a dimensionless adiabatic factor corresponding to Adiab, β is an modulation angular frequency. It can be shown that TBP has the relationship with β and μ as
 | (5.7) |
where T is the pulse width.
To satisfy the Adiabatic Condition, the parameter setting has to meet
 | (5.8) |
A RF macro that creates an adiabatic inversion RF pulse based on tanh/tan modulation. This macro contains attributes including:
The tanh/tan RF pulse is constructed from an adiabatic half passage and its time-reversed adiabatic half passage. The time dependence of the first adiabatic half passage is given by [8]:
 | (5.9) |
where A0 is the maximum B1 field corresponding to MaxB1, ξ = 10, tan(κ) = 20, T is the pulse width. The TBP can be estimated using
 | (5.10) |
A RF macro that creates an adiabatic B1 Independent Rotation (BIR) RF pulse. This macro contains attributes including:
The time dependence of the BIR-1 RF pulse is given by [6]:
Amplitude modulation:
 | (5.11) |
Frequency modulation:
 | (5.12) |
where A0 is the maximum B1 field corresponding to MaxB1, F0 is the maximum
RF frequency corresponding to MaxFreq. The RF pulse width is T = 
, and 
and ŷ
are unit vectors for indicating RF phase.
The time dependence of the BIR-2 RF pulse is given by [6]:
Amplitude modulation:
 | (5.13) |
Frequency modulation:
 | (5.14) |
where A0 is the maximum B1 field corresponding to MaxB1, F0 is the maximum
RF frequency corresponding to MaxFreq. The RF pulse width is T = 
, and 
and ŷ
are unit vectors for indicating RF phase.
The time dependence of the BIR-4 RF pulse is given by [6]:
Amplitude modulation:
![(| A tanh[λ(1- 4t)] 0 ≤ t < T
||{ 0 4t T T- 4T-
A(t) = A0tanh[λ(T -41t)] 4T ≤ t < 23T
|||( A0tanh[λ(3- T-)] 2-≤ t < 4-
A0tanh[λ(4Tt- 3)] 3T4 ≤ t ≤ T](MRiLab_User_Guide22x.png) | (5.15) |
Frequency modulation:
![(| tan(4βTt) T-
|||| tan(β)4t- 0 ≤ t < 4
{ tant[βa(nT(β -)2)] T4 ≤ t < T2
F(t) = || tan[β(4tT -2)] T≤ t < 3T
|||( tatna[βn((β4t)-4)] 23T 4
--tanT(β)-- 4-≤ t ≤ T](MRiLab_User_Guide23x.png) | (5.16) |
where A0 is the maximum B1 field corresponding to MaxB1. The RF pulse width is T. The λ and β are dimensionless constants that describe the degree to which extent the RF pulse satisfies the adiabatic condition.
A RF macro that creates an adiabatic B1 Independent Refocusing (BIREF) RF pulse. This macro contains attributes including:
The time dependence of the BIREF-1 RF pulse is given by [6]:
Amplitude modulation:
 | (5.17) |
Frequency modulation:
 | (5.18) |
where A0 is the maximum B1 field corresponding to MaxB1, F0 is the
maximum RF frequency corresponding to MaxFreq. The RF pulse width is
T = 
, and 
is an unit vector for indicating RF phase along the x axis.
The time dependence of the BIREF-2a RF pulse is given by [6]:
Amplitude modulation:
 | (5.19) |
Frequency modulation:
 | (5.20) |
where A0 is the maximum B1 field corresponding to MaxB1, F0 is the
maximum RF frequency corresponding to MaxFreq. The RF pulse width is
T = 
, and 
is an unit vector for indicating RF phase along the x axis.
The time dependence of the BIREF-2b RF pulse is given by [6]:
Amplitude modulation:
 | (5.21) |
Frequency modulation:
 | (5.22) |
where A0 is the maximum B1 field corresponding to MaxB1, F0 is the
maximum RF frequency corresponding to MaxFreq. The RF pulse width is
T = 
, and 
is an unit vector for indicating RF phase along the x axis.
A RF macro that creates a RF pulse with normally distributed pseudo-random amplitude. This macro is used for program testing purpose, however it shows that almost any arbitrary RF pulse could potentially be supported by MRiLab. This macro contains attributes including:
If the user has the RF pulse waveform data saved in a MAT file, the user can easily import the RF file into MRiLab pulse design interface by using ‘rfUser’ macro. The RF pulse MAT file needs to contain four matrices including ‘rfTime’ (i.e. RF time points) , ‘rfAmp’ (i.e. RF amplitude), ‘rfPhase’ (i.e. RF phase) and ‘rfFreq’ (i.e. RF frequency). All four matrices must have the same size of m-by-n, where m is the number of TR sections and n is the number of RF waveform points. In typical MR sequence, the entire sequence is composed of multiple TR sections. The ith TR section uses the ith RF pulse stored in the ith row of these four matrices. If the number of row is less than the number of TR sections, the last RF pulse will be used for all the remaining TR sections. Notice that if ‘rfPhase’ and/or ‘rfFreq’ are not provided, MRiLab initializes them as a value of 0. However, ‘rfTime’ and ‘rfAmp’ must be provided. Also note that MRiLab only uses the first RF pulse in the MAT file for pulse analysis in the RF pulse design interface. The ‘rfUser’ macro contains attributes including:
The RF pulse macro library covers several common types of RF pulse waveform. However, comprehensive coverage of existing and under developed RF pulses is nearly impossible for almost any pulse sequence design tools. To address this problem in MRiLab, the user can use the ‘rfUser’ to import RF pulses from files that are generated by other programs. Another way to import RF pulse is to simply write a RF macro. To create a RF macro, the user should follow the following steps :
It is strongly recommended to write your own RF macro code based on the closest RF macros in the MRiLab macro library, for example, the ‘rfRect’ macro is coded as:
Your macro must start from a function declaration at the beginning, then followed by attribute input section. The ‘tStart’ and ‘tEnd’ need to be added for indicating the time scale. It’s also strongly recommended to add attribute input ‘rfCoil’,‘Duplicates’ and ‘DupSpacing’ for multi-transmitting and multi-echo support.
The main code should deal with calculation for ‘rfAmp’, ‘rfPhase’, ‘rfFreq’ and ‘rfTime’. Notice that they should have the same size as 1-by-m where m is the number of RF waveform points.
Then you should add several lines to end your macro,
The RF macro file can be located anywhere in the computer as long as the file is included in Matlab searching path, however it is recommended to save the file under /SeqElem/rf for consistent file organization. Besides a RF macro file that performs pulse generation, MRiLab also requires a memo .txt file that accompanies the RF macro with the name ‘rfMacroName_Memo’. This file contains information about RF pulse description if necessary.
The customized RF macro needs to be registered in the macro library before using. To register a macro, open file ‘SeqElem.xml’ under /SeqElem, then add one entry under <rf> category with the proper attribute list. One example could be
Notice that in the above example, the first 7 attributes are required for MRiLab, The remaining attributes are optional based on user’s choice.
Once the RF macro is coded and registered to the library, the user can use this customized RF macro just like those default RF macros in the library.
The MR Sequence Design toolbox can be activated by pressing ‘Sequence Design Panel’ toolbar icon located at the top of the main simulation console. The current loaded sequence will show in the MR Sequence Design interface.
Figure 5.11 demonstrates an overview of the MR Sequence Design interface. This interface consists of
The Macro Library contains a full set of pulse macros for constructing MR sequence in MRiLab. It covers not only RF macro library as described in above section, but also GzSS, GyPE and GxR gradient macro library, ADC macro library and Ext macro library. The user needs to click the ‘SeqElem’ root as well as the subsequent nodes to unfold those macros.
In MRiLab, a MR sequence consists of the following parts :
The user can construct desired MR sequence by changing the content of the
MR sequence structure. To add a macro into the sequence structure, click one
macro in the macro library, then click on the sequence line root (e.g. rf) to
which this macro is inserted, then click ‘+’ macro operation button. To delete
a macro from the sequence structure, click the unwanted macro at
the sequence line, then click ‘-’ macro operation button. To duplicate
an existing macro, first click the source macro, then click ‘C’ macro
operation button for copying, click on the sequence line root, then
click ‘P’ macro operation button for pasting. MRiLab requires the
pulse macro being operated within its belonging category (e.g. RF
pulse can’t be added to gradient line). Also empty sequence line is
prohibited.
In MRiLab v1.2, multiple ‘Pulses’ are allowed in a single sequence structure
for enhancing design ability for complex MR sequence. For instance,
two ‘Pulses’ can be used to design a MR sequence with two separate
sections where one section is for regular image acquisition and the other
section is for fat saturation occurring every 5 regular image acquisition
sections (Figure 5.14). To add a new ‘Pulses’, click one ‘Pulses’ as a
source, then click ‘C’ macro operation button for copying, click on the
sequence root ‘MRiLabSeq’, then click ‘P’ macro operation button for
pasting. The duplicated ‘Pulses’ will be appended to the end of the
sequence structure, from where further modification could be made. Also,
removing a selected ‘Pulses’ can be performed by clicking ‘-’ operation.
The ‘Pulses’ has several properties:
Upon clicking on a pulse macro within a MR sequence structure, the corresponding macro attributes will be shown at the pulse attribute panel down below the sequence structure. The user can edit those attributes to modify the sequence waveform. To make any modification effective, the user must press ‘Update’ button to update the associated sequence XML file. Pressing ‘Execute’ button will update and redraw the MR sequence waveform plotting on this interface.
The sequence waveform associated with the sequence structure is displayed on
the ‘Sequence Diagram’ panel on the right side of this interface. The user can
use the waveform diagram to inspect sequence details and layout. The sequence
diagram consists of individual sequence lines corresponding to RF, GzSS,
GyPE, GxR, ADC and Ext, respectively. To accommodate multiple RF
transmitting, MRiLab provides separate RF sequence lines for each RF source.
When ‘MultiTransmit’ flag is turned on in the main control console and the
chosen sequence structure contains multiple RF pulses for different RF sources
(i.e. assign RF pulses to different coil channels by using ‘CoilID’ attribute),
the multi-tab will be activated on the ‘rf Source’ panel (Figure 5.15).
The user can switch between these tabs for checking individual RF
source.
Notice that the vertical axes for all sequence lines are normalized and the horizontal axes are in units of milliseconds. MRiLab provides a group of sequence display button (Figure 5.16) to help inspect the sequence waveform details.
The sequence display button group consists of :
The user can use the ‘Checker’ toggle button to display a sequence waveform at any arbitrary time interval (Figure 5.17). First press the ‘Checker’ button, move the mouse cursor into the axes. Notice that the mouse cursor changes to a cross-hair. Move the cross-hair in the axes, the amplitude value for each sequence line will be displayed accordingly on right side of each line with their default units. The user can click on the axes to choose one side of the time slot, then click on the another side. MRiLab will change the sequence view between the chosen time points, and also save time point information in the list at the bottom of this interface. To disable ‘Checker’ function, simple press this button again.
The ‘Waveform’ tab on the ‘Sequence Display’ contains parameters for controlling sequence wavefrom display.
The ‘KSpace’ tab on the ‘Sequence Display’ contains parameters for controlling k-space trajectory rendering.
Notice that in VTK rendering, the k-space line color starts from green and ends to red. If the user uses VTK for k-space rendering, please press keyboard ‘q’ to quit the VTK window before any subsequent simulation. Pressing the quit button on the VTK window under Linux system will force the entire Matlab to close, this is ‘believed’ to be a compatibility bug between Matlab and OpenGL which is used by VTK.
For the convenience of transferring data and configuration information across different modules, MRiLab defined several Matlab structure variables in the global scope. These structures start with ‘V’ standing for ‘Virtual Structure’. Understanding what these structures are and how they are working is important to work with MRiLab and to customize specific experiment design. There are at least two virtual structures that are useful for designing MR sequences.
The user can use the loop index variables in VVar
For example, to create 180∘ RF phase cycling in bSSFP sequence, the user can set the attributes for the excitation RF pulse as
A GzSS macro is a predefined module for a gradient pulse on the GzSS sequence line. MRiLab GzSS macro library is a collection of GzSS macros covering different gradient pulse types including slice selection and slice phase encoding pulses. Notice that by default the area under the gradient ramp is ignored. This section will give an introduction to each of the GzSS macros provided in MRiLab.
A GzSS macro that creates a typical slice selective gradient pulse (Figure 5.20). This macro contains attributes including:
Notice that both the prephasing gradient and rephasing gradient have half of the area of the slice selection gradient.
A GzSS macro that creates a slice selective gradient pulse straddled with crusher gradient (Figure 5.21). This macro contains attributes including:
A GzSS macro that creates a trapezoid gradient pulse (Figure 5.22) on GzSS sequence line. This macro contains attributes including:
A GzSS macro that creates a trapezoid gradient pulse of specified area (Figure 5.23) on GzSS sequence line. This macro contains attributes including:
A GzSS macro that creates a trapezoid gradient pulse of specified area with highest system performance (Figure 5.24) on GzSS sequence line. This macro creates a gradient pulse with nearly shortest pulse width for the given system hardware constraint. This macro contains attributes including:
A GzSS macro that creates a Cartesian phase encoding gradient pulse (Figure 5.25) along the slice direction. This macro contains attributes including:
Notice that the phase encoding gradient and the rephasing gradient have the same area that is automatically calculated based on the imaging parameters in the main control console.
If the user has the gradient pulse data saved in a MAT file, the user can easily import the gradient file into MRiLab by using ‘GzUser’ macro. The gradient pulse MAT file needs to contain two matrices including ‘GTime’ (i.e. gradient time points) and ‘GAmp’ (i.e. gradient amplitude). Both matrices must have the same size of m-by-n, where m is the number of TR sections and n is the number of gradient waveform points. In typical MR sequence, the entire sequence is composed of multiple TR sections. The ith TR section uses the ith gradient pulse stored in the ith row of these two matrices. If the number of row is less than the number of TR sections, the last gradient pulse will be used for all the remaining TR sections. The ‘GzUser’ macro contains attributes including:
A GyPE macro is a predefined module for a gradient pulse on the GyPE sequence line. MRiLab GyPE macro library is a collection of GyPE macros covering different gradient pulse types for performing phase encoding. Notice that by default the area under the gradient ramp is ignored. This section will give an introduction to each of the GyPE macros provided in MRiLab.
Similar to GzTrapezoid (Figure 5.22), GyTrapezoid creates a trapezoid gradient pulse on GyPE sequence line. This macro contains attributes including:
Similar to GzAreaTrapezoid (Figure 5.23), GyAreaTrapezoid creates a trapezoid gradient pulse of specified area on GyPE sequence line. This macro contains attributes including:
Similar to GzAreaTrapezoid2 (Figure 5.24), GyAreaTrapezoid2 creates a trapezoid gradient pulse of specified area with highest system performance on GyPE sequence line. This macro creates a gradient pulse with nearly shortest pulse width for the given system hardware constraint. This macro contains attributes including:
Similar to GzCartesian (Figure 5.25), GyCartesian creates a Cartesian phase encoding gradient pulse on GyPE sequence line. This macro contains attributes including:
Notice that the phase encoding gradient and the rephasing gradient have the same area that is automatically calculated based on the imaging parameters in the main control console.
A GyPE macro that creates a phase encoding gradient pulse for radial k-space trajectory (Figure 5.26) on GyPE sequence line. This macro contains attributes including:
Notice that both the prephasing gradient and rephasing gradient have half of the area of the phase encoding gradient that is automatically calculated based on the imaging parameters in the main control console. MRiLab requires the ‘Radial’ special technique tab to be loaded for properly configuring the ‘GyRadial’, ‘GxRadial’ and ‘ADCRadial’ macro. The user can set t2Middle value as ‘VCtl.TE’ to acquire the echo signal.
A GyPE macro that creates a phase encoding gradient pulse for spiral k-space trajectory (Figure 5.27) on GyPE sequence line. This macro contains attributes including:
Notice that the area of the phase encoding gradient is automatically calculated based on the imaging parameters in the main control console. MRiLab requires the ‘Spiral’ special technique tab to be loaded for properly configuring the ‘GySpiral’, ‘GxSpiral’ and ‘ADCSpiral’ macro. The user can set tStart value as ‘VCtl.TE’ to acquire the echo signal.
A GyPE macro that creates a FSE phase encoding gradient pulse train (Figure 5.28) on GyPE sequence line. This macro contains attributes including:
Notice that the phase encoding gradient and the rephasing gradient have the same area that is automatically calculated based on the imaging parameters in the main control console. MRiLab requires the ‘FSE’ special technique tab to be loaded for properly configuring the ‘GyFSE’, ‘GxFSE’ and ‘ADCFSE’ macro. To satisfy Carr Purcell Meiboom Gill (CPMG) condition and acquire echo signal at the center between two consecutive refocusing RF pulse, the effective TE value must equal (floor(FSE_ETL/2)+1)*FSE_ESP. The user can set tMiddle value as ‘VCtl.TE’ to acquire the echo signal, where the ‘VCtl.TE’ becomes the effective TE value.
A GyPE macro that creates an EPI phase encoding gradient pulse train (Figure 5.29) on GyPE sequence line. This macro contains attributes including:
Notice that the area of the prephasing gradient and the blip gradient are automatically calculated based on the imaging parameters in the main control console. MRiLab requires the ‘EPI’ special technique tab to be loaded for properly configuring the ‘GyEPI’, ‘GxEPI’ and ‘ADCEPI’ macro. The user can set t2Middle value as ‘VCtl.TE’ to acquire the echo signal, where the ‘VCtl.TE’ becomes the effective TE value.
If the user has the gradient pulse data saved in a MAT file, the user can easily import the gradient file into MRiLab by using ‘GyUser’ macro. The gradient pulse MAT file needs to contain two matrices including ‘GTime’ (i.e. gradient time points) and ‘GAmp’ (i.e. gradient amplitude). Both matrices must have the same size of m-by-n, where m is the number of TR sections and n is the number of gradient waveform points. In typical MR sequence, the entire sequence is composed of multiple TR sections. The ith TR section uses the ith gradient pulse stored in the ith row of these two matrices. If the number of row is less than the number of TR sections, the last gradient pulse will be used for all the remaining TR sections. The ‘GyUser’ macro contains attributes including:
A GxR macro is a predefined module for a gradient pulse on the GxR sequence line. MRiLab GxR macro library is a collection of GxR macros covering different gradient pulse types for performing frequency encoding. Notice that by default the area under the gradient ramp is ignored. This section will give an introduction to each of the GxR macros provided in MRiLab.
Similar to GzTrapezoid (Figure 5.22), GxTrapezoid creates a trapezoid gradient pulse on GxR sequence line. This macro contains attributes including:
Similar to GzAreaTrapezoid (Figure 5.23), GxAreaTrapezoid creates a trapezoid gradient pulse of specified area on GxR sequence line. This macro contains attributes including:
Similar to GzAreaTrapezoid2 (Figure 5.24), GxAreaTrapezoid2 creates a trapezoid gradient pulse of specified area with highest system performance on GxR sequence line. This macro creates a gradient pulse with nearly shortest pulse width for the given system hardware constraint. This macro contains attributes including:
A GxR macro that creates a Cartesian frequency encoding gradient pulse (Figure 5.30) on GxR sequence line. This macro contains attributes including:
Notice that both the prephasing gradient and rephasing gradient have half of the area of the frequency encoding gradient.
Similar to GyRadial (Figure 5.26), GxRadial creates a phase encoding gradient pulse for radial k-space trajectory on GxR sequence line. This macro contains attributes including:
Notice that both the prephasing gradient and rephasing gradient have half of the area of the phase encoding gradient that is automatically calculated based on the imaging parameters in the main control console. MRiLab requires the ‘Radial’ special technique tab to be loaded for properly configuring the ‘GyRadial’, ‘GxRadial’ and ‘ADCRadial’ macro. The user can set t2Middle value as ‘VCtl.TE’ to acquire the echo signal.
Similar to GySpiral (Figure 5.27), GxSpiral creates a phase encoding gradient pulse for spiral k-space trajectory on GxR sequence line. This macro contains attributes including:
Notice that the area of the phase encoding gradient is automatically calculated based on the imaging parameters in the main control console. MRiLab requires the ‘Spiral’ special technique tab to be loaded for properly configuring the ‘GySpiral’, ‘GxSpiral’ and ‘ADCSpiral’ macro. The user can set tStart value as ‘VCtl.TE’ to acquire the echo signal.
A GxR macro that creates a FSE frequency encoding gradient pulse train (Figure 5.31) on GxR sequence line. This macro contains attributes including:
Notice that the prephasing gradient has half of the area of the frequency encoding gradient that is automatically calculated based on the imaging parameters in the main control console. MRiLab requires the ‘FSE’ special technique tab to be loaded for properly configuring the ‘GyFSE’, ‘GxFSE’ and ‘ADCFSE’ macro. To satisfy CPMG condition and acquire echo signal at the center between two consecutive refocusing RF pulse, the effective TE value must equal (floor(FSE_ETL/2)+1)*FSE_ESP. The user can set t2Middle value as ‘VCtl.TE’ to acquire the echo signal, where the ‘VCtl.TE’ becomes the effective TE value.
A GxR macro that creates an EPI frequency encoding gradient pulse train (Figure 5.32) on GxR sequence line. This macro contains attributes including:
Notice that the area of the prephasing gradient and the frequency encoding gradient are automatically calculated based on the imaging parameters in the main control console. MRiLab requires the ‘EPI’ special technique tab to be loaded for properly configuring the ‘GyEPI’, ‘GxEPI’ and ‘ADCEPI’ macro. The user can set t2Middle value as ‘VCtl.TE’ to acquire the echo signal, where the ‘VCtl.TE’ becomes the effective TE value.
If the user has the gradient pulse data saved in a MAT file, the user can easily import the gradient file into MRiLab by using ‘GxUser’ macro. The gradient pulse MAT file needs to contain two matrices including ‘GTime’ (i.e. gradient time points) and ‘GAmp’ (i.e. gradient amplitude). Both matrices must have the same size of m-by-n, where m is the number of TR sections and n is the number of gradient waveform points. In typical MR sequence, the entire sequence is composed of multiple TR sections. The ith TR section uses the ith gradient pulse stored in the ith row of these two matrices. If the number of row is less than the number of TR sections, the last gradient pulse will be used for all the remaining TR sections. The ‘GxUser’ macro contains attributes including:
An ADC macro is a predefined module for an ADC flag pulse on the ADC sequence line. Signal acquisition starts when ADC flag is 1 and stops when ADC flag is 0. The ADC flag pulse is sampled at certain sampling rate that is determined by the imaging parameters (default by using ‘BandWidth’) in the main control console. MRiLab ADC macro library is a collection of ADC macros covering different pulse types for performing signal acquisition. This section will give an introduction to each of the ADC macros provided in MRiLab.
An ADC macro that creates an ADC flag pulse with user defined sampling rate on ADC sequence line. This macro contains attributes including:
An ADC macro that creates an ADC flag pulse for Cartesian readout on ADC sequence line. This macro contains attributes including:
An ADC macro that creates an ADC flag pulse for radial readout on ADC sequence line. This macro needs ‘Radial’ tab to be loaded. This macro contains attributes including:
An ADC macro that creates an ADC flag pulse for spiral readout on ADC sequence line. This macro needs ‘Spiral’ tab to be loaded. This macro contains attributes including:
An ADC macro that creates an ADC flag pulse train for FSE readout on ADC sequence line. This macro needs ‘FSE’ tab to be loaded. This macro contains attributes including:
An ADC macro that creates an ADC flag pulse train for EPI readout on ADC sequence line. This macro needs ‘EPI’ tab to be loaded. This macro contains attributes including:
If the user has the ADC pulse data saved in a MAT file, the user can easily import the ADC file into MRiLab by using ‘ADCUser’ macro. The ADC pulse MAT file needs to contain two matrices including ‘GTime’ (i.e. ADC time points) and ‘GAmp’ (i.e. ADC amplitude, use 1 for signal acquisition, 0 for no signal acquisition). Both matrices must have the same size of m-by-n, where m is the number of TR sections and n is the number of ADC sample points. In typical MR sequence, the entire sequence is composed of multiple TR sections. The ith TR section uses the ith ADC pulse stored in the ith row of these two matrices. If the number of row is less than the number of TR sections, the last ADC pulse will be used for all the remaining TR sections. The ‘ADCUser’ macro contains attributes including:
Notice that ‘ADCUser’ macro sets the first and last ADC sample points to 0 regardless of their original value, therefore the signal is not acquired at the first and last time points.
An Ext macro is a predefined module for an Ext flag pulse on the Ext sequence line. MRiLab specifies Ext signal for performing extended real time processes including calculating remaining scan time, manipulating k-space location and triggering object motion etc. Ext macro library only contains ‘ExtBit’ macro, however the ‘Ext’ attribute in this macro triggers different processes.
The ‘ExtBit’ macro (Figure 5.34) creates a triangle blip pulse on Ext sequence line. This macro contains attributes including:
Different Ext flags execute different extended real time processes during runtime scan. These extended processes are implemented using Plugin code in the /Plugin folder. MRiLab reserved several Ext flags for particular purposes.
The user can define Ext flags and use Ext Plugin to create extended real time process. To make your own Ext flag and Plugin code, you should follow the following steps :
It is strongly recommended to write your Plugin code based on a template like :
As mentioned before, VCtl encapsules all the simulation setting parameters in the main control console. VVar not only encapsules the loop index variables that MRiLab uses for generating MR sequence waveform, but also contains variables for temporarily buffering instant sequence line values during runtime. Do keep in mind, VCtl and VVar are read only, changing values inside these two structures may cause MRiLab crash.
Notice that there are three new Virtual Structures (VObj, VMag and VCoi) in this template, they store the variables about the virtual object, B0 field and coil B1 field which are accessible and editable in Plugin code. Do keep in mind, do not change the size of the matrices inside these three structures.
where ‘TxCoilNum’ is the number of transmitting coil channels, ‘RxCoilNum’ is the number of receiving coil channels.
The user needs to register customized Plugins before MRiLab can use it. To register Plugins and assign Ext flags to them, simply open ‘DoExtPlugin.m’ under /Src folder.
Add one more Switch case line, assign a distinct Ext flag, then add user defined Plugin function name under the case line. It is recommended to use negative Ext flag for user defined Plugin to make differences from system reserved plugins.
If the customized Plugin function modifies any variables in VObj, VMag or VCoi, the Plugin function needs to be registered for refreshing GPU device memory in case GPU parallel computing method is chosen. Simply open ‘DoGPUFetch.m’ under /Src folder.
Add one more Switch case line, assign VVar.gpuFetch equal to 1.
The user can make customized gradient macros and use them to create desired k-space trajectory. To make your own gradient macro, you should follow the following steps :
It is strongly recommended to write your own gradient macro code based on the closest gradient macros in the MRiLab macro library. One template is like :
The gradient macro file can be located anywhere in the computer as long as the file is included in Matlab searching path, however it is recommended to save the the file under corresponding gradient folder under /SeqElem folder for consistent file organization. The customized gradient macro needs to be registered in the macro library before using. To register the macro, open file ‘SeqElem.xml’ under /SeqElem, then add one entry under gradient category with the proper attribute list. One example could be
Notice that in the above example, the first 3 attributes are required for MRiLab, The remaining attributes are optional based on user’s choice.
Once the gradient macro is coded and registered to the library, the user can use this customized gradient macro just like those default gradient macros in the library.
To design a sequence in the MR Sequence Design interface, it is recommended to load
the sequence into the main control console first and then click toolbar icon to activate
the MR Sequence Design interface. This is mainly because the associated imaging
parameters that are necessary for configuring current sequence will also be loaded
during the sequence loading process. However, if the interface has already
been activated, the user can also use the sequence loading function to load
another sequence with current imaging parameters. To load a sequence,
click ‘Load’ menu then click ‘Load Sequence File’, choose a sequence XML
file.
Besides editing seuqence structue graphically, the user can also directly edit the sequence XML file using Matlab editor by click ‘XML’ then ‘Edit Seq XML’. After modification, the user needs to save changes for the XML file and then click ‘Refresh Seq Tree’ to update sequence structure and waveform.
The user can create a new MR sequence in the MR Sequence Design interface. To create a new sequence, click ‘New’ then click ‘Create Sequence File’. A sequence creation window (Figure 5.35) will show up and ask for new sequence name and notes. To follow MRiLab naming convention, the user is recommended to use ‘PSD_’ followed by a legal name string that is distinct to the existing sequences in MRiLab. Then click ‘OK’ to select a path for storing the sequence XML file. It’s strongly recommended to put the sequence under the MRiLab sequence root folder /PSD according to the sequence type so that the sequence is visible to MRiLab. Finally, MRiLab will create a new sequence XML file based on the content of ‘PSD_GRE3D’.
To design and optimize MR sequence, the user may need virtual objects with specific geometry and properties according to their experiment purpose. Although MRiLab provides a few phantoms with tissue properties mimicking several human tissue types, the user may still need to define customized virtual object. There are two ways of creating a new virtual object: 1) create phantom .mat file directly; 2) create phantom using MRiLab phantom design tool with XML.
To make a new virtual object using this method, you should follow the following steps :
Create a Matlab structure ‘VObj’. ‘VObj’ must contains variables including:
Then save the ‘VObj’ structure as a MAT file.
The current MRiLab version only supports two-pool MT model [9]. The ‘VObj’ must have the structure like:
Notice that the two-pool MT model needs to satisfy chemical equilibrium described as Rhof × Kfb = Rhob × Kbf. After making VObj, then save the ‘VObj’ structure as a MAT file. In MRiLab, the Bloch-equation solving kernel is only executed when the value of any sequence line needs to be updated. The time point at which this updating is happening is referred to as execution point. To accurately model MT exchange during scan, the user needs to create execution points on the entire RF sequence line. A typical method is to insert a long RF pulse with zero amplitude at the empty portion of the RF sequence line. The interested users are referred to PSD_SPGR3DMT for more information.
The current MRiLab version supports multiple spin exchange model up to any number of spin pools. The ‘VObj’ must have the structure like:
Notice that the multiple-pool ME model also needs to satisfy chemical equilibrium analogous to that of MT model. After making VObj, then save the ‘VObj’ structure as a MAT file. To accurately model ME exchange during scan, the user also needs to create execution points on the entire RF sequence line. A typical method is to insert a long RF pulse with zero amplitude at the empty portion of the RF sequence line. The interested users are referred to PSD_SPGR3DME for more information.
The Phantom Design toolbox can be activated by pressing ‘Phantom Design Panel’ toolbar icon located at the top of the main simulation console. Depending on whether or not a phantom XML file has been loaded (Chapter 3.1), the loaded phantom will show in the Phantom Design interface.
Figure 5.37 demonstrates an overview of the Phantom Design interface. This interface consists of
A VObj element macro is a predefined module for creating a VObj element that generates a 3D object with certain MR properties. MRiLab VObj element macro library is a collection of VObj element macros. This section will give an introduction to each of the VObj element macro provided in MRiLab.
A VObj element macro that creates a sphere object. This macro contains attributes including:
A VObj element macro that creates an ellipsoid object. This macro contains attributes including:
A VObj element macro that creates a cube object. This macro contains attributes including:
A VObj element macro that creates a cylinder object. This macro contains attributes including:
A VObj element macro that creates a pyramid object. This macro contains attributes including:
The user can also use the VObj loading function to load another VObj XML file. To
load a VObj, click ‘Load’ menu then click ‘Load VObj XML File’, choose a
VObj XML file. After the VObj XML is loaded, press ‘Render’ to display 3D
object.
The user can create a new VObj XML file in the Phantom Design interface. To create a new VObj, click ‘New’ then click ‘Create VObj XML File’. A VObj creation window will show up and ask for new VObj name and notes. To follow MRiLab naming convention, the user is recommended to use ‘VObj_’ followed by the phantom shape and applied anatomy (e.g. VObj_SphereHead), make sure that the new VObj name is distinct to the existing VObj XML names in MRiLab. Then click ‘OK’ to select a path for storing the VObj XML file. It’s strongly recommended to put the VObj XML under the MRiLab VObj root folder /VObj. Finally, MRiLab will create a new VObj XML file based on the content of ‘VObj_SphereHead’.
The Coil B1 Design toolbox can be activated by pressing ‘Coil Design Panel’ toolbar icon located at the top of the main simulation console. Depending on the coil mode (i.e. ‘Tx’ or ‘Rx’) highlighted on the ‘Coil Selection’ panel, the loaded coil will show in the Coil B1 Design interface.
Figure 5.39 demonstrates an overview of the Coil B1 Design interface. This interface consists of
The Coil Element Macro Library contains coil element macros for constructing coil structure in MRiLab. The user needs to click the ‘CoilElem’ root to unfold subsequent macros.
In MRiLab, a coil structure consists of arbitrary number of coil elements that are combined to create desired B1 field. The user can construct desired B1 field by changing the content within the coil structure. To add a macro into the coil structure, the user needs to click one macro in the macro library, then click on the coil structure root (i.e. MRiLabCoil) to which this macro is inserted, then click ‘+’ macro operation button. To delete a macro from the coil structure, the user needs to click the unwanted macro, then click ‘-’ macro operation button. To duplicate an existing macro, the user needs to first click the source macro, then click ‘C’ macro operation button for copying, click on the coil structure root, then click ‘P’ macro operation button for pasting. MRiLab doesn’t allow empty coil structure.
Upon clicking on the coil element macro within the coil structure, the corresponding macro attributes will be shown at the coil element attribute panel down below the coil structure. The user can edit those attributes to modify the coil element so as to generate different B1 field. To make any modification effective, the user must press ‘Update’ button to update the coil file. Pressing ‘Execute’ button will update and redraw the B1 field map on this interface.
The coil configuration and B1 field (T) generated based on the coil structure is displayed on the ‘Coil Sensitivity’ panel on the right side of this interface.
The ‘Display’ and ‘Grid’ tab on the ‘Coil Simulation’ panel contains parameters for controlling B1 field display.
MRiLab provides a group of B1 field display button (Figure 5.40) to help inspect the B1 field details.
The B1 field display button group consists of:
A coil element macro is a predefined module for creating a coil element that generates B1 field in three dimensional space. MRiLab coil element macro library is a collection of coil element macros covering simple coil geometries. This section will give an introduction to each of the coil element macro provided in MRiLab.
A coil element macro that creates a Biot-Savart coil circle. This macro contains attributes including:
If the user has the B1 field data saved in a MAT file, the user can easily import the B1 field into MRiLab coil design interface by using ‘CoilUser’ macro. The B1 field MAT file needs to contain two matrices including ‘B1x’ (i.e. x component of B1 field) and ‘B1y’ (i.e. y component of B1 field). Both of the two matrices must have the same size. The ‘CoilUser’ macro contains attributes including:
The user can also use the coil loading function to load another coil. To load a coil,
click ‘Load’ menu then click ‘Load Coil File’, choose a coil XML file. After the coil is
loaded, press ‘Execute’ to display field.
The user can create a new coil configuration in the Coil Design interface. To create a new coil, click ‘New’ then click ‘Create Coil File’. A coil creation window (Figure 5.42) will show up and ask for new coil name and notes. To follow MRiLab naming convention, the user is recommended to use ‘Coil_’ followed by the number of coil elements and applied anatomy (e.g. Coil_16ChChest), make sure that the new coil name is distinct to the existing coil names in MRiLab. Then click ‘OK’ to select a path for storing the coil XML file. It’s strongly recommended to put the coil under the MRiLab coil root folder /Coil according to the coil type so that the coil is visible to MRiLab. Finally, MRiLab will create a new coil XML file based on the content of ‘Coil_1ChHead’.
The Magnet dB0 Design toolbox can be activated by pressing ‘Magnet Design Panel’ toolbar icon located at the top of the main simulation console. The loaded magnet will show in the Magnet dB0 Design interface.
Figure 5.44 demonstrates an overview of the Magnet dB0 Design interface. This interface consists of
The Magnet Element Macro Library contains magnet element macros for constructing magnet structure in MRiLab. The user needs to click the ‘MagElem’ root to unfold subsequent macros.
In MRiLab, a magnet structure consists of arbitrary number of magnet elements that are combined to create desired dB0 field. The user can construct desired dB0 field by changing the content within the magnet structure. To add a macro into the magnet structure, the user needs to click one macro in the macro library, then click on the magnet structure root (i.e. MRiLabMag) to which this macro is inserted, then click ‘+’ macro operation button. To delete a macro from the magnet structure, the user needs to click the unwanted macro, then click ‘-’ macro operation button. To duplicate an existing macro, the user needs to first click the source macro, then click ‘C’ macro operation button for copying, click on the magnet structure root, then click ‘P’ macro operation button for pasting. MRiLab doesn’t allow empty magnet structure.
Upon clicking on the magnet element macro within the magnet structure, the corresponding macro attributes will be shown at the magnet element attribute panel down below the magnet structure. The user can edit those attributes to modify the magnet element so as to generate different dB0 field. To make any modification effective, the user must press ‘Update’ button to update the magnet file. Pressing ‘Execute’ button will update and redraw the dB0 field map on this interface.
The dB0 field (T) generated based on the magnet structure is displayed on the ‘Magnet Field’ panel on the right side of this interface.
The ‘Display’ and ‘Grid’ tab on the ‘Magnet Simulation’ panel contains parameters for controlling dB0 field display.
MRiLab provides a group of dB0 field display button to help inspect the dB0 field details. The dB0 field display button group consists of:
A magnet element macro is a predefined module for creating a magnet element that generates dB0 field in three dimensional space. MRiLab magnet element macro library is a collection of magnet element macros. This section will give an introduction to each of the magnet element macro provided in MRiLab.
A magnet element macro that creates a linear dB0 field. This macro contains attributes including:
A magnet element macro that creates a 3D Gaussian dB0 field. This macro contains attributes including:
A magnet element macro that creates a dB0 field based on symbolic equation. This macro contains attributes including:
The symbolic equation could be any legal Matlab equation using variables ‘X’, ‘Y’ and ‘Z’. For example, ‘X+Y’, ‘2*X.*Y’ and ‘2*sin(X)’ etc. Notice that use element operations for variables in the equation. The user needs to fill the equation between a pair of single quotes.
If the user has the dB0 field data saved in a MAT file, the user can easily import the dB0 field into MRiLab magnet design interface by using ‘MagUser’ macro. The dB0 field MAT file needs to contain one matrix ‘dB0’. The ‘MagUser’ macro contains attributes including:
The user can also use the magnet loading function to load another magnet. To load a
magnet, click ‘Load’ menu then click ‘Load Magnet File’, choose a magnet XML
file.
The user can create a new magnet in the Magnet Design interface. To create a new magnet, click ‘New’ then click ‘Create Magnet File’. A magnet creation window will show up and ask for new magnet name and notes. To follow MRiLab naming convention, the user is recommended to use ‘Mag_’ followed by a legal string and applied anatomy (e.g. Mag_CustomHead), make sure that the new magnet name is distinct to the remaining magnet names in MRiLab. Then click ‘OK’ to select a path for storing the magnet XML file. It’s strongly recommended to put the magnet under the MRiLab magnet root folder /Mag according to the magnet type so that the magnet is visible to MRiLab. Finally, MRiLab will create a new magnet XML file based on the content of ‘Mag_LinearHead’.
The Gradient Design toolbox can be activated by pressing ‘Gradient Design Panel’ toolbar icon located at the top of the main simulation console. The loaded gradient will show in the Gradient Design interface.
Figure 5.46 demonstrates an overview of the Gradient Design interface. This interface consists of
The Gradient Element Macro Library contains gradient element macros for constructing gradient structure in MRiLab. The user needs to click the ‘GradElem’ root to unfold subsequent macros.
In MRiLab, a gradient structure consists of three gradient elements that are combined to create gradient field for GzSS, GyPE and GxR. The user can construct desired gradient field by changing the content within the gradient structure. To add a macro into the gradient structure, the user needs to click one macro in the macro library, then click on the gradient structure root (i.e. MRiLabGrad) to which this macro is inserted, then click ‘+’ macro operation button. To delete a macro from the gradient structure, the user needs to click the unwanted macro, then click ‘-’ macro operation button. To duplicate an existing macro, the user needs to first click the source macro, then click ‘C’ macro operation button for copying, click on the gradient structure root, then click ‘P’ macro operation button for pasting. MRiLab doesn’t allow empty gradient structure, and also requires each of the three gradient sequence lines must have an individual gradient field.
Upon clicking on the gradient element macro within the gradient structure, the corresponding macro attributes will be shown at the gradient element attribute panel down below the gradient structure. The user can edit those attributes to modify the gradient element so as to generate different gradient field. To make any modification effective, the user must press ‘Update’ button to update the gradient file. Pressing ‘Execute’ button will update and redraw the gradient field map on this interface.
The gradient field is represented using a three-dimensional quiver plot on the ‘Gradient Field’ panel. If a constant unit gradient is used, the regular linear spatial location is applied. However, if non-unit gradient is used, the spatial location could be non-linear with spatial grid deformation. This means the original spatial location will be mapped to a new location in the spatial grid. The transformed spatial grid is represented as three slicing planes on the ‘Gradient Field’ panel. The value (color) of the spatial grid equals to the spatial location in the direction indicated by ‘GradLine’ in ‘Gradient Simulation’ panel.
The ‘Display’ and ‘Grid’ tab on the ‘Gradient Simulation’ panel contains parameters for controlling gradient field display.
MRiLab provides a group of grid display button to help inspect the grid details. The grid display button group consists of:
A gradient element macro is a predefined module for creating a gradient element that generates gradient field in three dimensional space. MRiLab gradient element macro library is a collection of gradient element macros. This section will give an introduction to each of the gradient element macro provided in MRiLab.
A gradient element macro that creates a linear gradient field. This macro contains attributes including:
A gradient element macro that creates a gradient field based on symbolic equation. This macro contains attributes including:
The symbolic equation could be any legal Matlab equation using variables ‘X’, ‘Y’ and ‘Z’. For example, ‘X+Y’, ‘2*X.*Y’ and ‘2*sin(X)’ etc. Notice that use element operations for variables in the equation. The user needs to fill the equation between a pair of single quotes.
If the user has the gradient field data saved in a MAT file, the user can easily import the gradient field into MRiLab gradient design interface by using ‘GradUser’ macro. The gradient field MAT file needs to contain one four dimensional matrix ‘G’ with the size of the fourth dimension equal to 3. G(:,:,:,1) is the x component of the gradient vector, G(:,:,:,2) is the y component of the gradient vector and G(:,:,:,3) is the z component of the gradient vector. The ‘GradUser’ macro contains attributes including:
The user can also use the gradient loading function to load another gradient. To load
a gradient, click ‘Load’ menu then click ‘Load Gradient File’, choose a gradient XML
file.
The user can create a new gradient in the Gradient Design interface. To create a new gradient, click ‘New’ then click ‘Create Gradient File’. A gradient creation window will show up and ask for new gradient name and notes. To follow MRiLab naming convention, the user is recommended to use ‘Grad_’ followed by a legal string and applied anatomy (e.g. Grad_CustomHead), make sure that the new gradient name is distinct to the existing gradient names in MRiLab. Then click ‘OK’ to select a path for storing the gradient XML file. It’s strongly recommended to put the gradient under the MRiLab gradient root folder /Grad according to the gradient type so that the gradient is visible to MRiLab. Finally, MRiLab will create a new gradient XML file based on the content of ‘Grad_LinearHead’.
The Motion Design toolbox can be activated by pressing ‘Motion Design Panel’ toolbar icon located at the top of the main simulation console.
Figure 5.48 demonstrates an overview of the Motion Design interface. This interface consists of
The Motion Element Macro Library contains motion element macros for constructing motion structure in MRiLab. The user needs to click the ‘MotElem’ root to unfold subsequent macros.
In MRiLab, a motion structure consists of arbitrary number of motion elements that are combined to create desired motion pattern. The user can construct desired motion pattern by changing the content within the motion structure. To add a macro into the motion structure, the user needs to click one macro in the macro library, then click on the motion structure root (i.e. MRiLabMot) to which this macro is inserted, then click ‘+’ macro operation button. To delete a macro from the motion structure, the user needs to click the unwanted macro, then click ‘-’ macro operation button. To duplicate an existing macro, the user needs to first click the source macro, then click ‘C’ macro operation button for copying, click on the motion structure root, then click ‘P’ macro operation button for pasting. MRiLab doesn’t allow empty motion structure.
Upon clicking on the motion element macro within the motion structure, the corresponding macro attributes will be shown at the motion element attribute panel down below the motion structure. The user can edit those attributes to modify the motion element so as to generate different motion pattern. To make any modification effective, the user must press ‘Update’ button to update the motion file. Pressing ‘Execute’ button will update and recalculate the motion track.
MRiLab uses Matlab Simulink 3D Animation to monitor the movement track of an imaging object in a motion tracker window. To open this window, the user needs to press ‘3D Play’ button. In the 3D animation, the imaging object is represented as a sphere or ellipsoid attached with three small spheres indicating axis directions (red for x axis, green for y axis and blue for z axis).
The ‘Display’ and ‘Replay’ tab on the ‘Motion Simulation’ panel contains parameters for controlling 3D animation.
A motion element macro is a predefined module for creating a motion element that generates a movement track in three dimensional space. MRiLab motion element macro library is a collection of motion element macros. This section will give an introduction to each of the motion element macro provided in MRiLab.
A motion element macro that creates translation motion. This macro contains attributes including:
The displacement equation could be any legal Matlab equation using variables ‘t’. For example, ‘2*t’, ‘t+200e-3’ and ‘0.05*sin(0.1*t)’ etc. Notice that the user needs to fill the equation between a pair of single quotes.
A motion element macro that creates rotation motion. This macro contains attributes including:
The rotation angle equation could be any legal Matlab equation using variables ‘t’. For example, ‘2*t’, ‘t+200e-3’ and ‘sin(0.1*t)’ etc. Notice that the user needs to fill the equation between a pair of single quotes.
The user can also use the motion loading function to load another motion. To load a
motion, click ‘Load’ menu then click ‘Load Motion File’, choose a motion XML
file.
The user can create a new motion in the Motion Design interface. To create a new
motion, click ‘New’ then click ‘Create Motion File’. A motion creation window will
show up and ask for new motion name and notes. To follow MRiLab naming
convention, the user is recommended to use ‘Mot_’ followed by a legal string and
applied anatomy (e.g. Mot_CustomHead), make sure that the new motion name is
distinct to the existing motion names in MRiLab. Then click ‘OK’ to select a
path for storing the motion XML file. It’s strongly recommended to put
the motion under the MRiLab motion root folder /Mot according to the
motion type so that the motion is visible to MRiLab. Finally, MRiLab will
create a new motion XML file based on the content of ‘Mot_ShiftHead’.
Note that adding a motion pattern is not guaranteed to stimulate motion, the user also needs to use extended real time process to trigger motion at the Ext sequence line. To trigger motion, one or more Ext flag 8 needs to be inserted into Ext line. An accurate motion tracking can be achieved using both small time interval of the motion track sample steps and frequent motion triggering, which typically requires more simulation computing. The interested users are referred to PSD_GRE3D for more information.
MRiLab provides default image reconstruction code for a few types of Cartesian and Non-Cartesian k-space reconstruction. External reconstruction code is also acceptable.
To choose default reconstruction for Cartesian readout, the user needs to choose ‘Cartesian’ for ‘ReconType’ under the ‘Recon’ tab. The Cartesian reconstruction can be applied to typical Cartesian readout, FSE readout and EPI readout using default gradient macros. To choose default reconstruction for Non-Cartesian readout, the user needs to choose ‘NonCart’ for ‘ReconType’. The corresponding Non-Cartesian reconstruction code can be applied to radial readout and spiral readout. Notice that the Non-Cartesian reconstruction performs 2D gridding process for the Non-Cartesian k-space trajectory using a Kaiser-Bessel kernel, followed by a regular iFFT. The 2D gridding process should also in theory be applicable to other Non-Cartesian readout. Also the ‘gridding’ tab is required to perform Non-Cartesian reconstruction.
If the user designed a special k-space trajectory that requires particular reconstruction code, the user needs to indicate using external reconstruction by changing ‘ReconEng’ to ‘External’, and then provides a reconstruction function quoted with a pair of single quotes for ‘ExternalEng’. It is recommended to put the external code under /Recon/External, if not, make sure the reconstruction code is in Matlab searching path. This setting will simply ignore default reconstruction code and apply external code. It is strongly recommended to write your own reconstruction code based on the template :
Notice that there are two new Virtual Structures (VSig and VImg) in this template, VSig encapsules acquired MR signal. VImg is declared to store reconstructed images. For the structure ‘VSig’, MRiLab provides :
The sample points in these arrays are organized in the order of
Sample points in one readout < Multiple echos < First phase encoding < Second
phase encoding < Coil channel < Spin species
For the structure ‘VImg’, MRiLab provides :
where RXDim, RY Dim and RZDim are reconstructed image resolution in three spatial directions.
If the user are interested in using Gadgetron for image reconstruction, MRiLab also provides a simple MEX code to convert the acquired data into ISMRMRD file which can be used in Gadgetron process. To activate this function, the user needs to install ISMRMRD dependency packages to properly run compiled interface MEX. I am currently working on improving MRiLab support to Gadgetron recon framework. And I will be very pleased to talk with any MRiLab users who are willing to contribute to improving MRiLab Gadgetron support. Please don’t hesitate to contact me. The ISMRMRD relevant code is ‘DoToHDF5.m’ under /Src and ‘DoMatToHDF5’ under /Lib/src/interface.
MRiLab can save simulation output into two file formats including ‘MAT’ and ‘ISMRMRD’. The user can choose ‘OutputType’ under ‘Recon’ tab. If the user choose ‘ISMRMRD’ format, the ‘DoMatToHDF5’ MEX has to be functional, if not, MAT file will be saved instead. MRiLab saves simulation output for each series into a folder named by MRiLab’s startup time under /Output folder. For MAT file, MRiLab saves:
MRiLab incorporated a set of image display and analysis tools which are designed using Matlab GUIDE, and carefully tuned for manipulating MRiLab generated multi-dimensional image data.
The user can right click on any MRiLab graphical axes to create an individual figure with the identical graphical content.
MRiLab incorporated a toolbox called ‘MatrixUser’ for performing image display and analysis. This toolbox can be activated by pressing ‘MatrixUser’ toolbar icon located at the top of the main simulation console.
MatrixUser will search through the current output folder and load all image series from this folder into Matlab base workspace. The MatrixUser main window (Figure 6.2) works as a matrix manager for loaded images. The user can choose to display image series by using the pop-up menu. The matrix size, type and value range are calculated and provided on the right side. The user can press ‘MatrixUser’ button to activate MatrixUser display window. Current MatrixUser version supports displaying any valid Matlab multi-dimensional matrix and Matlab structure variable.
By default, MatrixUser reads Matlab base workspace, scans existing matrices in the Matlab session, then creates a matrix list for tracking matrix content. Once those matrices are updated by the user, MatrixUser will also update the matrix list. Moreover, there are several different approaches to import data from outside Matlab into MatrixUser. The imported matrices will be saved into Matlab base workspace. The import functions are located under ‘Load’ menu, including:
The default Matlab .mat file is natively supported by MatrixUser.
If image content exists in the system clipboard, it can be converted into a RGB image which contains a three slice matrix with each slice corresponds to an individual Red, Green and Blue channel.
MatrixUser takes a full screenshot for current monitor and saves it into a RGB image as described above.
Binary data file is supported by MatrixUser. The user needs to properly configure loading parameters (Figure 6.3) according to the matrix size and data type information.
MatrixUser supports loading multiple DICOM files by using a file filter interface (Figure 6.4). The user needs to load DICOM files into the loading interface by selecting desired DICOM files (multiple selection supported). The selected files are listed in the DICOM file list. The user can click any single DICOM file to read associated DICOM header and image preview. To manually create a matrix using DICOM files, choose files from the DICOM file list, press ‘>>>>>>’ to push the files into selected DICOM file list, provide a matrix name, press ‘Convert’ button to create a matrix based on chosen DICOM files. The user can load those created matrices into base workspace by pressing ‘Load matrix’ button.
MatrixUser supports loading DICOM files in a batch mode. This function requires the path of the folder containing DICOM files is provided. MatrixUser will try to create separate matrices for DICOM files coming from different image series. A matrix selection interface will provide converted matrices with loading functions.
NIfTI file with .nii suffix is supported by MatrixUser.
To activate MatrixUser display window, press ‘MatrixUser’ button. If the selected matrix contains complex value, four options are available for displaying magnitude, phase, real and imaginary of the matrix. Figure 6.5 demonstrates an overview of the window layout of the MatrixUser display window. The window consists of
Matlab toolbar provides basic interactive functions for displaying matrix. These functions include:
: Save current image axes into an image file
: Zoom in matrix area
: Zoom out matrix area
: Manually move matrix position
: Check individual voxel value and index
: Print current figure
: Turn on/off color barMost of the matrix analysis functions are represented on function bench panel. MatrixUser groups these functions into categories and dynamically loads them according to the dimension size and compatibility of current display matrix. A multi-tab is used to contain individual function button associated with each function. The tabs under the multi-tab are used to switch between function categories, which include
The matrix calculator consists of three control items, including a matrix
expression editbox, an execution button ( 
) and a matrix saving button (
). Valid matrix calculation expression can be executed in the calculator
and updated in the display window, serving as a convenient way to analyze
matrix calculation result. Matrix concatenation and recombination can also be
done in the calculator, for example, to side-by-side compare multiple 3D
matrices (Figure 6.6). Some valid calculation examples are, but not limited
to:
where A, B, C and D are multi-dimensional matrices with proper matrix size. Also note that the source matrices have to stay in the base workspace for being referenced. Pressing the execution button will perform the calculation and save the result as a temporary matrix. The user can also save the temporary matrix into workspace by pressing matrix saving button. The saved temporary matrix will have a ‘_tmp’ suffix by default.
The display axes renders an image for one slice of current matrix. The user can use mouse cursor to inspect the coordinate and value of any voxel. Moving mouse wheel back and forth moves the slice location along current dimension and updates the display axes.
The matrix color control group provides a set of sliders, editboxes and popup menu which help control image color scheme and contrast. This group consists of
MatrixUser measures the dimension size of the display matrix and assigns one slider and editbox for each dimension that is above 2 (i.e. no slider and editbox for the first and second dimension). These control items are located in individual dimension tab and can be used to switch among slices in current active dimension.
Matrix display functions are listed under this tab.
: Reset matrix display and erase additional display effect
: Turn on and off black grid line on the image display axes
: Open an instant magnifier which zooms in specific image
area
: Plot and update a profile curve along a resizable checking
line (Figure 6.7)
: Plot and update a profile curve along a matrix dimension (Figure
6.8)
: Open a separate window with two matrix display axes (Figure
6.9) displaying another two orthogonal images. The operation buttons on
the second window consists of
: Activate or deactivate localizer line on main display
: Activate or deactivate localizer line on main display
: Switch matrices between main display and second
display. This operation simply permutes current matrix into its
orthogonal version. The user can save the transformed matrix
using ( ).
: Create a RGB image, assign current slice and following two slices
to Red, Green and Blue channel, respectively
: Create a montage image using multiple slices (Figure
6.10)
: Overlap two matrices with the same matrix size (Figure 6.11),
notice that the user can press to remove foreground matrix from
overlapping with background matrix.
This function category performs quick math calculation for current matrix. A few commonly used math calculation are provided under this tab. Instead, complex calculation can be performed using matrix calculator as mentioned above.
: Calculate absolute value
: Calculate negative value
: Calculate natural logarithm
: Calculate base 10 logarithm
: Calculate exponential
: Calculate the power of 10
: Calculate sine
: Calculate cosine
: Calculate tangent
: Calculate inverse sine
: Calculate inverse cosine
: Calculate inverse tangent
This function category performs spatial transformation or fast Fourier transform (FFT) to current matrix.
: Flip matrix horizontally (along the first dimension)
: Flip matrix vertically (along the second dimension)
: Flip matrix along slice direction (the third dimension)
: Rotate matrix 90 degree in the counter clockwise direction
: Rotate matrix 90 degree in the clockwise direction
: Rotate matrix certain degree along an axis specified using
the rotation axis origin and direction in the 3D space
: Translate matrix along certain direction
: Perform multi-dimensional FFT for current matrix, the user
needs to specify up to which dimension to perform FFT.This function category performs basic matrix processing functions.
: Create binary mask based on given threshold
: Perform smoothing operation to current matrix
: Perform sharpening operation to current matrix
: Perform edge detection to current matrix
: Provides various image filters (Figure 6.12)
: Add noise to matrix (Figure 6.13)
: Replace voxel value for the voxels within certain value range and
outside a polygon area. The user needs to draw a polygon first (double
click to confirm the polygon).
: Replace voxel value for the voxels within certain value range and
inside a polygon area. The user needs to draw a polygon first (double click
to confirm the polygon).
: Replace voxel value for the voxels inside a polygon area. The
user needs to draw a polygon first (double click to confirm the
polygon).
: Replace matrix area with a selected matrix source region. The
user needs to draw a free-hand area (source region), drag the free-hand
region to target matrix area, then double click to confirm the
operation.
: Crop current matrix using a rectangle box (double click to
confirm the cropping)
: Extract parts of current matrix using irregular shape (double
click to confirm the extracting)
: Resample current matrix by using chosen interpolation method
(Figure 6.14). The user can specify sampling factors in x, y and z direction
for 3D matrix.
MatrixUser provides a set of function buttons for performing Region-of-Interest (ROI) analysis (Figure 6.15). To create a ROI, the user needs to click ROI button first, then draw a ROI on the image axes. The statistical measures (i.e. mean, standard deviation and relative standard deviation) for voxels in delineated ROI is calculated and updated with moving ROI position or changing ROI shape. The ROI function buttons consists of
: Draw a free hand ROI
: Draw a rectangle or square ROI
: Draw a circle or ellipse ROI
: Draw a polygon ROI
: Draw a straight line for measuring distance in units of pixels
: Draw a polygon for measuring the interior angles in degrees
: Record existing ROI shape and location into a ROI list,
allow to redraw selected ROI in multiple image axes. To redraw a
existing ROI, the user needs to select a ROI in the list, then press
‘Show’ button. Note that the copied ROI is no longer resizable and
movable.
: Plot histogram for current slice (Figure 6.16); if ROIs exist,
plot histogram for latest activated ROI
MatrixUser supports functions for performing multi-slice manual segmentation. To create a segmentation, click segmentation button, then draw a region on the image axes. The user can modify the region location and shape prior to confirming segmentation with double click. The segmentation buttons consists of
: Do a free-hand segmentation
: Do a circle or ellipse segmentation
: Do a polygon segmentation
: Edit segmentation
: Save segmentation into a MAT file
: Load segmentation from a MAT fileTo edit segmented region (Figure 6.17), press to open a segmentation
manager. The manager records the type and location for existing segmented
regions. The user can click any region item to inspect the location of the region.
To edit chosen region, click ‘Edit’ button to activate the region outline. Both
the shape and mask flag are editable for segmented region. After editing, click
‘Update’ to conform modification. The user can press to save current
segmentation into a MAT file which contains a mask matrix and a cell array
storing segmentation location information. The user can also press to
save the mask matrix into workspace. Pressing can load previous
segmented regions from a saved MAT file. Notice that the user can
press to remove segmentation from overlapping with background
matrix.
This function category generates surface or mesh plot for current image.
: Create contour plot of current matrix
: Create 3D contour plot of current matrix
: Create filled 2D contour plot
: Create 3D shaded surface plot
: Create surface plot and contour
: Create surface plot with colormap based lighting
: Create mesh plot
: Create mesh plot and contour
: Create a curtain around a mesh plot
: Create a ribbon plot
: Create a waterfall plot
: Create pcolor (checkerboard) plotMatlab default image tools (Figure 6.18) are tailored for MatrixUser and included in this category.
: Perform imtool for current image
: Perform immovie for playback current 3D matrix
: Perform imcontrast for adjusting image contrastUncategorized functions are categorized under this tab.
: Create a 3D graph for rendering current matrix (Figure
6.19)
: Perform projection along a given matrix dimension. Support
multi-dimensional matrix projection
: Perform 3D projection along x, y or z axis with certain angle
increment (Figure 6.20)
: Reslice 3D matrix at given direction. The user needs to draw a
line for indicating the slicing direction with double click for confirmation
(Figure 6.21)
: Create a movie using current matrix display. Support making
movie for overlapped matrices.
The arrayShow tool is a Matlab image viewer which has been designed for the evaluation of multidimensional complex images. arrayShow is originally designed by Tilman Johannes Sumpf at Biomedizinische NMR Forschungs GmbH. The user can press ‘arrayShow’ button to activate this viewer. Detailed information about arrayShow can be found at http://www.biomednmr.mpg.de/index.php?option=com_content&task=view&id=137&Itemid=43;
The SpinWatcher is designed for monitoring spin evolution behavior within a single voxel at given MR sequence and field environment. This function can be activated by pressing ‘SpinWatcher’ toolbar icon located at the top of the main simulation console.
Figure 6.23 demonstrates an overview of the SpinWatcher main interface. This interface consists of
. The slider beside the image can help change
image slices.
The spin properties will be automatically updated with a selected voxel. The user can modify the spin properties and environment to meet their own needs. The editable properties provided in this interface include:
The SpinWatcher supports monitoring multiple spin species. The user needs to provide an array of multiple values for T1, T2, T2*, Rho and ChemShift, and give the correct number of spin species. The values must be separated with space. For example
SpinWatcher provides two plots for capturing the spin evolution (i.e. |Mxy| and Mz) regarding time. Press ‘Execute’ button to recalculate the spin evolution plot if changes to spin property and environment was made. The settings can be saved into a file by pressing ‘Update’. To export temporary variables of spin evolution into Matlab base workspace, press ‘Export’, the exported variables include :
The user can also undock the spin evolution plot by pressing ‘∧’ button.
(:TODO) SARWatcher is a graphical toolbox for monitoring real time spatial Specific Absorption Rate (SAR) of the virtual object under given experimental design. This toolbox is still under developing.
(:TODO) SeqConverter is a graphical toolbox for converting MRiLab MR sequence format to more portable sequence format. This toolbox is still under developing.
This chapter shows a few examples for demonstrating the applications of MRiLab simulation
This example (Figure 7.1) simulates the dark banding artifact in bSSFP images arisen from non-uniform B0 field. To perform this simulation, the following steps are needed:
The user can adjust the ‘FlipAng’, ‘TR’ and ‘TE’ to modify the pattern of the banding artifact.
This example (Figure 7.2) simulates chemical shift artifact at the interface of water and fat in a GRE sequence. To perform this simulation, the following steps are needed:
The user can adjust the ‘BandWidth’ and ‘FreqDir’ to modify the appearance of the chemical shift.
This example (Figure 7.3) simulates multiple RF transmitting using a bSSFP sequence. To perform this simulation, the following steps are needed:
The user can adjust the ‘B1Level’ to modify the actual flip angle, modify the RF pulse using MR sequence Design Toolbox for individual RF source, or modify the coil configuration for generating desired B1+ field.
This example (Figure 7.4) simulates multiple receiving using a SE sequence. To perform this simulation, the following steps are needed:
The user can adjust the coil configuration for generating desired B1- field. All eight channels will be receiving MR signal from the virtual object individually.
This example (Figure 7.5) simulates applying non-unit gradient with a 3D SPGR sequence. To perform this simulation, the following steps are needed:
The user can adjust the gradient structure for generating desired gradient field. Notice that this applied gradient in GyPE GradLine has a factor of 0.5 in the Y direction. This will cause image contraction in the Y direction.
This example (Figure 7.6) simulates motion artifact with a 3D GRE sequence. To perform this simulation, the following steps are needed:
The user can adjust the motion structure to generate different motion track patterns, and/or modify motion triggering in the Ext sequence line to sample object movement.
[1] V.L. Yarnykh: Actual Flip-Angle Imaging in the Pulsed Steady State: A Method for Rapid Three-Dimensional Mapping of the Transmitted Radiofrequency Field , Magn. Reson. Med., 57, (2007), 192-200.
[2] J.I. Jackson, C.H. Meyer, D.G. Nishimura, and A. Macovski: Selection of a Convolution Function for Fourier Inversion Using Gridding , IEEE Trans. Med. Imag., vol. 10, no. 3, pp 473-478, 1991.
[3] V. Rasche, R. Proska, R. Sinkus, P. Boernert, and H. Eggers: Resampling of Data Between Arbitrary Grids Using Convolution Interpolation , IEEE Trans. Med. Imag., vol. 18, no. 5, pp 385-392, 1999.
[4] P.J. Beatty, D.G. Nishimura, and J.M. Pauly: Rapid gridding reconstruction with a minimal oversampling ratio , IEEE Trans. Med. Imag., vol. 24, no. 6, pp 799-808, 2005.
[5] G.H. Glover: Simple Analytic Spiral k-space Algorithm , Magn. Reson. Med., 42, (2005), 412-415.
[6] M.A. Bernstein, K.F. King, X.J. Zhou: Handbook of MRI Pulse Sequences , Elsevier Academic Press, 2004.
[7] J. Pauly, P. Le Roux, D.G. Nishimura, and A. Macovski: Parameter relations for the Shinnar-Le Roux selective excitation pulse design algorithm , IEEE Trans. Med. Imag., vol. 10, no. 1, pp 53-65, 1991.
[8] T. Hwang, P.C.M. van Zijl and M. Garwood: Fast Broadband Inversion by Adiabatic Pulses , J. Magn. Reson., 133, pp 200-203, 1998.
[9] V.L. Yarnykh: Pulsed Z-Spectroscopic Imaging of Cross-Relaxation Parameters in Tissues for Human MRI: Theory and Clinical Applications , Magn. Reson. Med., 47, (2002), 929-939.
I am indebted to all my teachers and mentors. I would like to thank Dr. Neil Gelman at The Western University (Canada) for introducing me into the MRI field and inspiring me for developing the MatrixUser project. I would also like to thank Drs. Wally Block and Richard Kijowski at The University of Wisconsin-Madison (USA) who guide me to acquire knowledge of MR sequence design and medical image application. My gratitude is owed to Dr. Alexey Samsonov at The University of Wisconsin-Madison (USA) for inspiring me developing MT relevant functions. Many people also contribute significantly to the MRiLab project through publishing free code online which largely extends MRiLab functionality, in particular, Dr. Tilman Johannes Sumpf at Biomedizinische NMR Forschungs GmbH (Germany), Dr. John Pauly and Dr. Brian Hargreaves at Stanford University (USA). Finally, my appreciation goes to my wife Zhaoye Zhou who supports me for finishing the whole project.
While MRiLab has been carefully designed and tuned for performing high quality MRI simulation, bugs and misfunctions may still exist. Moreover, several important parts are still missing in MRiLab, including MR spectrum simulation, water diffusion and Eddy-Current simulation etc. I am also working to further optimize solving kernel for better performance and to enhance the compatibility with Gadgetron. The MRiLab project is open to the whole MRI community, any user who are interested to improve MRiLab is very welcome to do so. I will be very pleased if you can leave me feedback and ideas for better enhancing MRiLab functionality. I will also be very happy to talk about any kinds of collaboration for future MRiLab development. Please don’t hesitate to contact me (leoliuf@gmail.com).
