QSMxT Recon

What it does

OpenRecon runs a container inside the scanner's reconstruction system. QSMxT Recon is QSMxT in that container.

Before you start

At the scanner

• A Siemens MR scanner with OpenRecon licensed and enabled. Install routines differ between XA60/XA61 and XA70 / Numaris X VA70 and later (including XB10/VB10) — both are covered below.
• Administrator access to the MRAWP host, since the package is installed from a console.

The acquisition

• A plain gradient-echo (GRE) sequence with both magnitude and unfiltered phase reconstruction enabled. Filtered phase from an SWI sequence will not work as input.
• Magnitude and phase must have matching echoes and the same distortion-correction setting.
• Single-echo and multi-echo both work. T2* and R2* maps need multi-echo.

There is an example Siemens 3 T GRE protocol to start from — five echoes at 5, 10, 15, 20 and 25 ms. Check the acquisition and safety settings against your own site's before you use it. It also stores different reconstruction settings from the package defaults, so look over the OpenRecon controls after loading it.

To build the package

• Docker, Python 3 and 7-Zip on a machine you control — a laptop is fine. The build pulls a container image of a few GB, so give it the disk and the bandwidth.
• You do not need scanner access to build; you only need it to install.

Build the package

The build wraps the Neurodesk QSMxT container in the OpenRecon metadata and start command that the scanner expects, then zips it. On macOS, brew install python p7zip covers the prerequisites; on Linux use your package manager.

1. Clone the recipe repository and set up its Python environment. The build script refuses to install anything unless a virtualenv is active.
   git clone https://github.com/neurodesk/openrecon.git cd openrecon python3 -m venv .venv source .venv/bin/activate python -m pip install jsonschema packaging
2. Build from the recipe directory. This pulls the QSMxT container if it is not already in your local Docker cache, so expect it to take a while the first time.
   cd recipes/qsmxt /bin/bash ../build.sh

   Pass --local-cache instead to require an image that is already cached and skip the pull — useful for an offline build. In that mode the script asks whether you want the OpenRecon artifact, the FIRE one, or both.

3. You end up with two artifacts, both named for the QSMxT version in the recipe's params.sh (9.19.1 at the time of writing):
   OpenRecon_neurodesk_qsmxt_V9.19.1.zip ← the scanner package FIRE_neurodesk_qsmxt_V9.19.1/ ← for the WIP 070 FIRE framework

Install it on the scanner

Copy the zip to the scanner host without extracting it. Close every open protocol first — an open protocol will block the install.

XA70 / Numaris X VA70 and later (XB10, VB10)

These use the Numaris/Edge routine for installing OpenRecon applications.

1. Exit Kiosk mode on the MRAWP with Tab + Del + Num +.
2. Create C:\Temp\OR\Packages and copy the zip there, still zipped.
3. Open an elevated administrator CMD shell and change to the Numaris/Edge directory:
   cd /d "%MREDGEHOME%"
4. Install the package:
   syngo.MR.Digi.Utils.Console.exe store --install-package "C:\Temp\OR\Packages\OpenRecon_neurodesk_qsmxt_V9.19.1.zip"
5. Installation takes several minutes. Repeat this until the package shows up as installed:
   syngo.MR.Digi.Utils.Console.exe store --list

XA60 and XA61

1. Copy the zip, unextracted, to the file-transfer drop folder:
   C:\Program Files\Siemens\Numaris\OperationalManagement\FileTransfer\incoming
2. Wait for the zip to disappear from incoming — that is the watcher picking it up.
3. Watch the install in C:\ProgramData\Siemens\Numaris\log\syngo.MR.HostInfra.OpenRecon.Watcher. It first writes a 0 KB file named for the container and version, which should then grow to roughly 100–200 KB.
4. Once that log is written, open a protocol and check the package is listed.
5. Run the sequence with OpenRecon enabled and check C:\ProgramData\Siemens\Numaris\log\OpenRecon.utr for errors.

Run a reconstruction

With the package installed, in the OpenRecon controls of your GRE protocol:

1. Select qsmxt as the reconstruction package, and leave config on qsmxt.
2. Set Input images to match your acquisition. The default is Distortion corrected.
3. For a first run, leave Pipeline preset on Custom algorithm controls with QSM algorithm = HD-QSM, Unwrap = ROMEO, Background = iSMV.
4. Leave Mask preset on BET (recommended).
5. Leave Output maps on QSM only. Keep Send original on if you also want the source magnitude and phase series in the database.
6. Run the acquisition with OpenRecon enabled. When reconstruction finishes, the QSMxT QSM series appears next to the original images.

The controls

Input images

If reconstruction reports missing input images, check that both magnitude and unfiltered phase exist for the correction setting you picked.

Output maps

Send original controls whether the source magnitude and phase come back too. Turn it off to keep only the selected outputs.

Reconstruction method

Pipeline preset picks a predefined combination of processing stages, and also offers complete methods — QSMART, TGV, AutoQSM, NeXtQSM, iQSM and iQSM+. The packaged deep-learning methods run offline on the CPU. A preset overrides the three stage controls; choose Custom algorithm controls to set them yourself:

• Unwrap removes phase jumps. OpenRecon default: ROMEO.
• Background removes background-field contributions. Default: iSMV.
• QSM algorithm calculates susceptibility. Default: HD-QSM.

Default in a stage control means the OpenRecon default above — note these differ from the QSMxT command-line defaults. Reconstruction time depends on the method, the acquisition and the hardware. The QSMxT algorithm reference describes what each one does.

Brain mask

The mask defines what gets reconstructed. To see its coverage next to the map, set Output maps to All available.

• Start with BET (recommended). If it is cutting off brain tissue, lower BET threshold from its default of 0.5 to grow the mask.
• Robust threshold and BET + threshold union are the threshold-based alternatives; the union takes anything either method selected. Threshold input picks the image to threshold, Threshold method picks Otsu or Percentile, and Mask percentile applies only to Percentile.
• Mask cleanup fills holes and closes small gaps. Default: close and fill holes.

Mask settings apply independently of the pipeline preset.

Running it under FIRE instead

The same container also builds a bundle for the WIP 070 FIRE framework. It is installed and configured separately from the OpenRecon package, and it is the route to take if you want the reconstruction to run somewhere other than the scanner.

• Chroot on MARS is what the bundle ships configured for. Merge the Ice folder into MriCustomer as INSTALL_FIRE.txt describes; start_chroot=true is already set, so there is nothing to configure.
• Docker on another machine is the option when the reconstruction needs more memory than MARS has. Run the container on the scanner-internal network or through the SSH tunnel FIRE opens, set start_chroot=false, and point the ini file's hostname and port at it.

The container serves on port 9002, the same as the upstream kspacekelvin/fire-python server:

Full configuration — ini files for both the direct and tunnelled cases, and the detached long-lived variant — is in neurodesk/openrecon#292.

Where to go next

Citation

Stewart, Ashley Wilton, Simon Daniel Robinson, Kieran O'Brien, et al. “QSMxT: Robust Masking and Artifact Reduction for Quantitative Susceptibility Mapping.” Magnetic Resonance in Medicine 87, no. 3 (2022): 1289–300. https://doi.org/10.1002/mrm.29048