Usage Guide

Command-Line Reconstruction

Basic Invocation

./release/recon <config.toml>

The tool reads the TOML configuration, performs reconstruction, and writes output to the path specified in [output] filename.

Batch Reconstruction

Use the provided shell script to run multiple configurations:

./run.sh config1.toml config2.toml config3.toml

This runs each configuration sequentially.

Alternatively, manually loop over configurations:

for config in configs/*.toml; do
  ./release/recon "$config"
done

Input Data

Projection TIFF Files

Input projection data should be stored in TIFF format. The file can contain:

  • Multiple 2D frames (multi-frame TIFF)

  • A single 3D stack (as a grayscale TIFF volume)

Angles File

Create a text file with one projection angle per line:

0.0
1.5
3.0
...

Auto-detection:

  • If any angle has magnitude > 2π, all angles are treated as degrees and converted to radians

  • Otherwise, angles are treated as radians

Generate angles with a helper script:

scripts/angles.sh 0 90 > angles.txt

This creates integer degree angles from 0° to 90°.

Output Files

TIFF Output

By default, reconstructions are saved as TIFF. The output is a 3D array with dimensions specified by recon_dims in the configuration.

VTI Output (ParaView Format)

To also save the reconstruction in VTI format (compatible with ParaView/VisIt):

[output]
filename = "recon.tiff"
formats  = ["tiff", "vti"]

This creates both recon.tiff and recon.vti.

Python Utility Scripts

Estimate GPU Memory

Analytically estimate the peak GPU memory required for split Bregman + conjugate gradient:

python scripts/estimate_bregman_memory.py --shape 256 256 256

Options:

  • --shape N N N: Volume dimensions (required)

  • --dtype float32 or --dtype float64: Data type (default: float32)

  • --verbose: Print detailed breakdown

Test MBIR Pipeline Memory

Estimate GPU memory from a configuration file:

python scripts/test_bregman_memory.py dino/tv/config.toml

Options:

  • --verbose: Print detailed breakdown

  • --sino-shape Na Nr Nc: Override sinogram shape (optional)

Visualize Reconstruction

Display slices of a reconstructed TIFF volume:

python scripts/plot_chess.py recon.tiff

Opens a matplotlib window showing three cross-sectional slices. Useful for quick quality assessment.

Alias:

python scripts/plot_projs.py recon.tiff  # Identical functionality

Plot NUFFT Error

Plot numerical error vs. kernel radius for NUFFT parameters:

python scripts/run_nufft.py          # Generate error data
python scripts/plot_error.py         # Visualize results

This sweeps over different NUFFT oversampling and kernel parameters, runs the NUFFT forward/backward test, and plots the reconstruction error.

Performance Optimization

Parallel Execution

The library uses multiple parallelization strategies:

  • OpenMP: Multi-threaded CPU execution (set OMP_NUM_THREADS to control cores)

  • Intel TBB: Fine-grained task parallelization

  • FFTW: Optimized fast Fourier transforms (multi-threaded)

  • FINUFFT: Non-uniform FFT for polar grid operations

  • CUDA (optional): GPU-accelerated forward/backward projections and optimization

Using GPU

If compiled with CUDA support, the tool automatically uses GPU acceleration if available. Disable with:

export CUDA_VISIBLE_DEVICES=  # Empty string disables CUDA
./release/recon config.toml

Controlling Thread Count

For OpenMP:

export OMP_NUM_THREADS=4
./release/recon config.toml

Troubleshooting

Configuration Errors

If the TOML file has errors, the tool prints a message and generates config_template.toml as a reference.

Memory Issues

Use the memory estimation scripts to check if your system has sufficient RAM or VRAM:

python scripts/estimate_bregman_memory.py --shape 325 303 303 --verbose

Convergence Issues

If reconstruction does not converge or has artifacts:

  1. Reduce lambda for less aggressive regularization

  2. Increase max_iters for more iterations

  3. Increase inner_iters to solve the u-subproblem more accurately

  4. Adjust mu (higher enforces constraints more strictly)

Example Workflows

Single-Tilt Reconstruction

# Create angles
scripts/angles.sh 0 180 > angles.txt

# Create config.toml with [[input]] gamma = 0

# Run reconstruction
./release/recon config.toml

# Visualize
python scripts/plot_chess.py recon.tiff

Multi-Tilt XMCD

# Prepare three datasets with gamma = 0, ±45

# Create config.toml with three [[input]] blocks

# Run once (combines all three tilts)
./release/recon config.toml

# Result is a single 3D reconstruction
python scripts/plot_chess.py recon.tiff

Batch Processing

# Run all configs in a directory
for config in experiments/*/config.toml; do
  echo "Processing $config..."
  ./release/recon "$config"
done