Reconstruction pipeline for MRI raw data acquired with Pulseq or JEMRIS

This repository contains a reconstruction pipeline for MRI data acquired with Pulseq [1] or with the MR simulator JEMRIS [2]. The data is reconstructed using the BART MRI Toolbox [3].

Installation

Clone the repository with the submodule: git clone --recursive https://github.com/mrphysics-bonn/python-ismrmrd-reco.git. A uv and a Docker installation are required to run the reconstruction server. Additionally, the following steps have to be done:

1. After Docker installation, add your user to the docker group (execute sudo groupadd docker, sudo usermod -aG docker $USER and newgrp docker)
2. Pull the Docker image of the reconstruction server from Dockerhub: docker pull mavel101/reco_server.
3. Install the reconstruction dependencies, including the local python-ismrmrd-server submodule, with uv sync.

To activate the virtual environment manually:

source .venv/bin/activate

Deactivate it with:

deactivate

Activation is optional; commands can also be run directly with uv run.

Optional dependencies for the creation of MR sequences with PyPulseq [4] can be installed with uv sync --extra seqdev.

Quick start guide - from sequence to image

In this quick start, Cartesian and spiral sequences are created with PyPulseq. The raw data collected with this sequence, is reconstructed and images are displayed.

Creating a sequence:

1. Install the sequence dependencies with uv sync --extra seqdev.
2. Run the Python scripts with python write_spiral.py or python write_cartesian.py in the directory "example_sequences/pypulseq". At the top of both scripts, protocol parameters and the sequence filename can be changed.
3. A Pulseq file (.seq) is created in the same directory and an MRD (originally ISMRMRD) metadata file (.h5) is created in the folder "dependency/metadata". This metadata file is important for the reconstruction, as raw data obtained from Pulseq sequences does not contain any information, on how the kspace was acquired.

Running a reconstruction:

1. Start the Docker container by running ./start_docker mavel101/reco_server. The reconstruction server is now running in the background. You can attach to the container with docker attach #containerID (optional, check ID with docker ps).
2. Run client commands through the uv environment with uv run.
3. Run a reconstruction by sending the data to the server.
   Example Pulseq reconstruction: ./send_data pulseq example_data/scanner/raw_spiralout_gre_fatsat_7T.h5 recon/out.h5. Example JEMRIS reconstruction: ./send_data jemris example_data/simu/signals_spiralout_clean_slc30.h5 recon/out.h5.
4. Logging information and debug files can be found in the "debug" folder.
5. In this example, the reconstructed image is stored in "recon/out.h5". The image can be viewed by running the Python script "plot_img.py". Images are stored in MRD image format. Image files will not be overwritten, but new images will be appended to existing files.

More example raw data files are located in "example_data". Raw data conversion for Siemens data to MRD [5] is described below.

Example sequences and data

The relevant files for reconstruction are placed in subfolders:

• "example_data": Contains raw datasets from real MR scanners and from simulation with JEMRIS [2], that can be reconstructed with the pipeline.
• "example_sequences": Contains the Pulseq sequence files, raw data was acquired with, as well as the source code for Python/PyPulseq sequences (incl. MRD metadata creation) and XML files for JEMRIS sequences
• "dependency": Contains reconstruction dependencies, mainly the MRD metadata files
• "recon": Contains reconstructed images in hdf5 file.

The non-Cartesian example data provided in this repository was acquired with a spiral sequence and the reconstruction uses the GIRF predicted [6] spiral k-space trajectory.
Additional example sequences, installation instructions and documentation regarding JEMRIS can be found on the projects website: https://github.com/JEMRIS/jemris/.
Pulseq sequence files can be converted to the GE compatible format TOPPE, using the converter at https://github.com/toppeMRI/PulseGEq.

Further information on the reconstruction server

Docker image (latest build, GPU support, startup scripts)

If you want to build the docker image from the latest Dockerfile in this repository, the following steps are required:

• Clone the repository and run git submodule update --init
• Run ./build_docker from the project folder. This builds the docker image on your system.

The default docker image contains only CPU based reconstructions. A Docker image with GPU support can be build with: ./build_docker python-ismrmrd-server/ bart_cuda

The container can be started by executing ./start_docker from the project folder:

• ./start_docker bart starts the container and runs the reconstruction server in background until it is killed with docker kill #containerID, where "#containerID" is the ID of the container (check with docker ps). You can attach to the container with docker attach #containerID.
• Use ./start_docker --gpu bart_cuda for GPU support

Sending data via the client

Reconstruction can be started via the provided client.py from the "python-ismrmrd-server" folder. The client and its local submodule dependency are installed by uv sync, and commands can be run with uv run.

To run an example spiral reconstruction:

• The send_data script accepts pulseq, jemris, or pg as its first argument. For example, ./send_data pulseq example_data/scanner/raw_spiralout_gre_fatsat_7T.h5 recon/out.h5 reconstructs a spiral dataset.
• By default, reconstructed data will be located in "recon/out.h5".
• Reconstructed images can be plotted with the plot_img.py script.
• Debug files (in npy format) and a log file are stored in the "debug" folder
• The above command extends to python python-ismrmrd-server/client.py -c bart_pulseq -g images -o recon/out.h5 example_data/scanner/raw_spiralout_gre_fatsat_7T.h5. The option "-c" selects the configuration name for the current reconstruction, which is evaluated in server.py and starts the respective reconstruction script. Available options are "bart_pulseq" for Pulseq reconstructions and "bart_jemris" for JEMRIS reconstructions. The option -o defines the image output path and option -G defines the group name of the output images in the hdf5 file.
• The script plot_img.py can be used to view reconstructed images via the Python library matplotlib

Reconstruction of Pulseq data

For reconstruction of Pulseq data, a MRD metadata file has to be provided. This metadata file has to contain all necessary information for reconstruction such as counters, flags and other metadata. The metadata file has to be located in "dependency/metadata".
IMPORTANT: The metadata filename has to be saved in the first user defined string parameter ("userParameterString") of the raw data ISMRMRD file in order to access the metadata in the reconstruction.

For Siemens data this is can automatically be done at file conversion:

1. The metadata file should have the same name as the sequence.
2. The sequence/metadata filename has to be stored in the free text parameter "tFree" of the raw data file. This is automatically done in the newest Pulseq interpreter sequence (v1.4.0).
3. The raw data is converted to the MRD format with the siemens_to_ismrmrd converter (https://github.com/ismrmrd/siemens_to_ismrmrd). After installation of the converter, send_data pulseq can handle Siemens raw data acquired with the Pulseq sequence. The script uses the parameter maps in "python-ismrmrd-server/parameter_maps" for file conversion.
4. Metadata merging is done by the functions "insert_hdr" and "insert_acq" in "python-ismrmrd-server/pulseq_helper.py".

Reconstruction of JEMRIS simulation data

Reconstruction of JEMRIS simulation data can be started within JEMRIS by selecting the "-r" option, when running JEMRIS in the command line or by starting the recon in the GUI with the "start reco" button. However, the following prerequisites have to be met:

• The Docker image of the reconstruction server has to be pulled from Dockerhub (docker pull mavel101/reco_server). If JEMRIS is running from the command line, the reconstruction server also has to be started.
• The client.py (and its dependencies) has to be installed in the environment where the JEMRIS simulation is executed. This lets you execute the client from anywhere. Run uv sync from this repository to install it from the local submodule.

Reconstruction of already simulated data can also be started by running ./send_data jemris as described in "Sending data via client".

Extend & Modify existing reconstruction

Use ./start_docker --interactive to mount the reconstruction codebase in the active container and start an interactive docker session in the bash shell. Add --gpu for GPU support. Run start_server within the container to start the reconstruction server. If you leave the session, the container is killed. Note, that the dependencies in the codebase might have changed and the latest build of the Docker container might be necessary to run reconstructions. . Changes to the reconstruction scripts will immediately applied in a new reconstruction started. If subscripts are altered, a restart of the reconstruction server might be necessary. Some important scripts are explained in more detail:

• server.py: New reconstruction scripts can be added here and a new configuration name should be assigned. The new reconstruction can be started sending data via client.py with the new configuration name by using the "-c" option (see above).
• pulseq_helper.py: Contains the funtions for mirroring metadata information from the metadata file to the streamed raw data.
• bart_pulseq.py: Launches a BART reconstruction pipeline for Pulseq data, depending on the trajectory type

Static offresonance correction & higher order image reconstruction

Static offresonance correction is available via the PowerGrid reconstruction toolbox [7]. For this, a different Docker image is needed, which can be pulled with docker pull mavel101/bart_pg_gpu (Nvidia GPU required). Alternatively build the image with ./build_docker python-ismrmrd-server/ bart_pg_gpu. Run ./start_docker --gpu mavel101/bart_pg_gpu to start the server. An example reconstruction can be started with ./send_data pg example_data/scanner/raw_spiralout_gre_fatsat_7T.h5.

The reconstruction script for a B0-corrected reconstruction is located in "python-ismrmrd-server/powergrid_pulseq.py". It is possible to use an external field map located at "dependency/fmap.npz" (as in the above example) or to calculate a field map from a calibration scan within the same sequence. The unit of the field map has to be rad/s. For more information, contact the author.

Higher order image reconstruction [8] is also possible, if data from a field camera is available in the trajectory field of the MRD file. For more information on the data structure, see "python-ismrmrd-server/powergrid_pulseq_ho.py" or contact the author.

Author

Forward all questions and feedback to the author:
Marten Veldmann (marten.veldmann@dzne.de)

References

[1] Layton, K. J. et. al. Pulseq: A rapid and hardware-independent pulse sequence prototyping framework, MRM, 2017;77(4):1544-1552, http://pulseq.github.io/

[2] Stöcker, T. et. al. High-Performance Computing MRI Simulations, MRM, 2010;64:186-193, https://www.jemris.org/

[3] BART Toolbox for Computational Magnetic Resonance Imaging, DOI: 10.5281/zenodo.592960, https://mrirecon.github.io/bart

[4] Ravi, Keerthi, Sairam Geethanath, and John Vaughan. "PyPulseq: A Python Package for MRI Pulse Sequence Design." Journal of Open Source Software 4.42 (2019): 1725., https://github.com/imr-framework/pypulseq

[5] Inati, J. I. et. al. ISMRM Raw data format: A proposed standard for MRI raw datasets, MRM, 2017;77(1):411-421, https://ismrmrd.github.io

[6] Vannesjo, S. J. et al. Gradient System Characterization by Impulse Response Measurements with a Dynamic Field Camera. MRM 2013;69:583-593

[7] Cerjanic, A. et al. PowerGrid: A open source library for accelerated iterative magnetic resonance image reconstruction, Proc. Intl. Soc. Mag. Res. Med., 2016, http://mrfil.github.io/PowerGrid/

[8] Wilm, BJ et. al. Higher Order Reconstruction for MRI in the Presence of Spatiotemporal Field Perturbations. MRM, 2011;65(6):1690–1701