Code Design
This code is structured to enable integration of custom reconstruction and analysis modules into the MRD streaming framework without the need to modify the streaming framework code itself. There are a set of core files that implement the client/server of the MRD streaming framework itself and a set of example analysis modules. Custom modules are added as additional .py files which are selected at runtime by the client via the config string. There are also a set of utility functions that perform common tasks.
Data flow
In the MRD streaming framework, the client is defined as having the source data and the server analyzes the data and sends it back to the client. A client.py is included in this repo and reads data from an MRD HDF5 file, but this role may be played by an MRI scanner in deployment.
The server receives data from the client over a TCP network socket. The server selects a Python module from the client config value. For example, invertcontrast resolves to invertcontrast.py. The --defaultConfig (-d) value in main.py is used to specify a default config file if real-time selection fails. When packaged in a Docker application, it can also specify the intended default configuration of the application. The --savedata option can be used to have the server save a copy of the data it receives from the server. The resulting MRD file can be used for subsequent calls by client.py. This workflow may be useful when saving data streamed from an external source, e.g. directly from an MRI scanner.
Module design
Several example module files are provided, with invertcontrast.py being the most general example. Each module must have the entry point function process(connection, config, mrdHeader), which receives a continuous stream of data from the client.
Inside the process() function for modules is a for loop that iterates over each data received from the client.
for item in connection:
# ----------------------------------------------------------
# Raw k-space data messages
# ----------------------------------------------------------
if isinstance(item, ismrmrd.Acquisition):
# Accumulate all imaging readouts in a group
if (not item.is_flag_set(ismrmrd.ACQ_IS_NOISE_MEASUREMENT) and
not item.is_flag_set(ismrmrd.ACQ_IS_PARALLEL_CALIBRATION) and
not item.is_flag_set(ismrmrd.ACQ_IS_PHASECORR_DATA) and
not item.is_flag_set(ismrmrd.ACQ_IS_NAVIGATION_DATA)):
acqGroup.append(item)
# When this criteria is met, run process_raw() on the accumulated
# data, which returns images that are sent back to the client.
if item.is_flag_set(ismrmrd.ACQ_LAST_IN_MEASUREMENT):
logging.info("Processing a group of k-space data")
image = process_raw(acqGroup, connection, config, mrdHeader)
connection.send_image(image)
acqGroup = []
This basic design separates out each data item (readout, image, waveform), collects the data into a list (acqGroup), and determines whether or not to trigger an analysis on the accumulated data via the process_raw() function. The filtering (e.g. excluding noise data, phase correction data, etc.) is application specific and should be adjusted as needed. The triggering condition (ACQ_LAST_IN_MEASUREMENT in this example), can be used to perform "real-time" analysis of the data before all data is collected. For example, if the criteria were changed to ACQ_LAST_IN_SLICE, process_raw() would be triggered to perform a reconstruction as soon as acquisition for each slice has completed.
Core files
main.py: Main entrypoint for starting the MRD server via theServerclassserver.py: Handles communication with the client via the MRD streaming session protocol, select an analysis module based on the requested config, and executes processingconnection.py: Handles parsing of individual MRD message types within an MRD streaming sessionconstants.py: Definition of MRD message type constantsmrdhelper.py: Helper utilities for MRD metadata and image handlingclient.py: Main entry point for starting the MRD client, which sends MRD data and receives results
Example modules
invertcontrast.py: Primary example module. Accepts raw k-space acquisitions (2D/3D) or image data, inverts image contrast (with support for JSON configuration parameters like colormaps/RGB output, pixel shifting, and ROI overlays), and returns the processed imagessimplefft.py: Simplified alternate code structure for modules. Performs basic Cartesian 2D FFT image reconstruction from raw k-space acquisitions, including sum-of-squares coil combination, intensity normalization, and oversampling removalanalyzeflow.py: Image analysis module. Processes phase-contrast velocity images, performs background noise masking based on mean temporal differences across cardiac phases, and outputs images grouped by flow encoding directionreport.py: Generates a synthetic summary report image with acquisition parameters and measurement information rendered via matplotlib, embedding values into MetaAttributes for downstream parsingbartfire.py: Reconstructs raw k-space data by interfacing with the BART (Berkeley Advanced Reconstruction Toolbox) library (e.g., ESPIRiT coil calibration and parallel imaging reconstruction). Note that this requires that BART library be compiled, such as withdocker\bart\Dockerfilespectroscopy.py: Processes single-voxel MR spectroscopy (MRS) or MR spectroscopic imaging (MRSI) data, including coil selection, oversampling removal, spectral/spatial reconstruction, and result plotting.filter.py: An example custom module derived from invertcontrast.py that demonstrates applying a SciPy median filter to reconstructed image data.
Utility files
generate_cartesian_shepp_logan_dataset.py: Creates Cartesian Shepp-Logan phantom raw datadicom2mrd.py: Converts DICOM folders to MRD image filesmrd2dicom.py: Converts MRD image files to DICOM foldersmrd2gif.py: Creates animated GIF previews from MRD images