Monitor a reconstruction

FORGE's reconstruction programs report their progress as JSON lines. forgeview turns that stream into a full-screen terminal monitor with the log, a progress bar per stage with an estimated finish time, sparklines of the solver's error norm and penalty, the GPU memory in use in CUDA builds, and a live image preview of the current solution. Images are drawn with the iTerm2 or Kitty graphics protocol when the terminal supports one, and with half-block characters otherwise. This page shows the common ways to watch a run. The output options and the JSON lines protocol are in the reference.

The recording is a CPU build reconstructing a synthetic 128 × 128, 8-coil radial scan with 4 time segments. Images are drawn with half-block characters here; in iTerm2 or Kitty the preview is a full-resolution image. To record it again, run scripts/forgeview-demo/make-gif.sh.

Watch a run in your terminal

Run the program in a terminal. It starts forgeview for you:

forgeSense -i data.h5 -o recon/ -F NUFFT -n 20

Press q or Esc to quit the monitor. When the reconstruction finishes, forgeview exits and prints a summary.

This works when stdout is a terminal and the program can find the forgeview executable. It looks in this order:

1. The directory the reconstruction program is in
2. ../tools/forgeview/forgeview relative to that directory
3. The FORGEVIEW_PATH environment variable
4. Your PATH

After cmake --install, forgeview is in <prefix>/bin and the programs are in <prefix>/bin/<backend>, so put <prefix>/bin on your PATH or set FORGEVIEW_PATH. When running from a build directory, set FORGEVIEW_PATH=build/tools/forgeview/forgeview.

If forgeview can't be started, the program prints plain log lines instead.

Watch a run on another machine

Keep the program writing JSON lines with --no-tui, and pipe them into forgeview on your own machine:

ssh gpu-server 'cd /data/run && forgeSense -i data.h5 -o recon/ -F NUFFT -n 20 --no-tui' 2>&1 | forgeview

The same pipe works locally: forgeSense [options] --no-tui 2>&1 | forgeview.

Save the progress to a file

forgeSense [options] --jsonl-output run.jsonl

The file can be read later by your own scripts. Each line is one JSON object.

Read the progress from another program

Use --no-tui so forgeview is never started, and read JSON lines from the program's stderr. FORGE Studio runs the programs this way. If you'd rather read stdout, use --jsonl-output stdout.

Get plain text

forgeSense [options] --no-jsonl

This prints ordinary coloured log lines and text progress bars, with no JSON. It is the easiest mode to read in a CI log or a batch job's output file.

Find the log afterwards

Every run also writes a rotating log file, forge.log, in the current directory, whichever mode you choose. Use --log-level debug for more detail.