◆ FORGE Suite
GitHubMechanical Neuroimaging Lab · Univ. of Delaware
Skip to content

Your first reconstruction

In this tutorial you will make a small synthetic dataset, reconstruct it with forgeSense, and look at the images it writes. It takes about five minutes and needs no scanner data.

You need a working FORGE install. If you don't have one yet, follow Install the dependencies and Build and install FORGE first. The commands below assume the installed layout, with a backend directory and bin/ on your PATH:

export PATH="$HOME/forge/bin/cpu:$HOME/forge/bin:$PATH"   # or bin/metal, bin/cuda

Check that the shell finds the programs:

forgeSense --version

It prints a line such as FORGE v0.14.0 (forgeSense) built 2026-11-04.

Make a test dataset

FORGE reads raw data from ISMRMRD HDF5 files. GenSyntheticISMRMRD writes one for you, with coil sensitivity maps and a field map already inside.

Work in a new directory:

mkdir forge-tutorial && cd forge-tutorial
GenSyntheticISMRMRD -o sense.h5 -x 64 -y 64 -c 4 -k 128 -r 128

This makes a 64 × 64 Shepp-Logan phantom seen by 4 coils, sampled along 128 radial spokes of 128 samples. You now have a file called sense.h5.

Reconstruct it

The output directory has to exist before you start, so make it first:

mkdir -p recon
forgeSense -i sense.h5 -o recon/ -F NUFFT -t 1 -n 10 -B 0.001

The options say:

  • -F NUFFT: use the gridding NUFFT as the forward model.
  • -t 1: use one time segment. This dataset has no off-resonance, so there is nothing to correct.
  • -n 10: run 10 conjugate gradient iterations.
  • -B 0.001: add a small quadratic regularization.

If you run this in a terminal and forgeview is on your PATH, a full-screen monitor opens. It shows the log, a progress bar, a plot of the solver's error falling with each iteration and a preview of the image as it forms. When the reconstruction finishes, the monitor closes and prints a summary. Here it is on a larger synthetic dataset with off-resonance:

forgeSense reconstructing a synthetic radial scan while forgeview shows progress bars, convergence sparklines, the log and a live image preview

If forgeview isn't found, you see ordinary log lines instead. Either way, FORGE also writes a log file, forge.log, in the current directory.

Look at the result

List the output directory:

ls recon/

img_Slice0_Rep0_Avg0_Echo0_Phase0_mag.nii
img_Slice0_Rep0_Avg0_Echo0_Phase0_phs.nii

The dataset has one slice, one repetition and so on, so you get one image, written as a magnitude file and a phase file. Open the magnitude file in any NIfTI viewer, such as FSLeyes, ITK-SNAP or 3D Slicer. You should see the synthetic phantom.

Try a second run

The solver improves the image a little with every iteration. To see this, stop it after 2 iterations:

mkdir -p recon-n2
forgeSense -i sense.h5 -o recon-n2/ -F NUFFT -t 1 -n 2 -B 0.001

Open recon-n2/img_Slice0_Rep0_Avg0_Echo0_Phase0_mag.nii next to the first result. After 2 iterations the image is blurred and its intensity is uneven, because the solver has only recovered the coarse, low-frequency part of the image. After 10 iterations the edges are sharp.

What you did

You generated an ISMRMRD dataset, reconstructed it with iterative SENSE, and saw how the number of iterations changes the image.

From here: