llnl / leap

comprehensive library of 3D transmission Computed Tomography (CT) algorithms with Python API and fully integrated with PyTorch

LivermorE AI Projector for Computed Tomography (LEAP)

This is a C++/CUDA library of 3D tomographic algorithms (pre-processing algorithms, projectors, and analytic (FBP) and iterative reconstruction algorithms) with a Python interface. The projectors (forward and back projection) are implemented for both multi-GPU and multi-core CPU and we provide bindings to PyTorch to achieve differentiable forward and backward projectors for AI/ML-driven Computed Tomography (CT) applications.

There are a lot of CT reconstruction packages out there, so why choose LEAP? In short, LEAP has more accurate projectors and FBP algorithms, more features, and most algorithms run faster than other popular CT reconstruction packages, but here is a more detailed list:

1. Seamless integration with PyTorch using torch.nn.Module and torch.autograd.Function to enable differentiable forward and backward projectors for AI/ML-driven Computed Tomography (CT) applications.
2. Quantitatively accurate, matched (forward and back) projector pairs that model the finite size of the voxel and detector pixel; very similar to the Separable Footprint method [Long, Fessler, and Balter, TMI, 2010]. These matched projectors ensure convergence and provide accurate, smooth results. Unmatch projectors or those projectors that do not model the finite size of the voxel or detector pixel may produce artifacts when used over enough iterations [DeMan and Basu, PMB, 2004].
3. Multi-GPU and multi-core CPU implementations of all algorithms that are as fast or faster than other popular CT reconstruction packages.
4. Algorithms not limited by the amount of GPU memory.
5. Flexible 3D CT geometry specification that allows users to specify arbitrary shifts of the source and detector positions, non-uniform angular spacing, and more.
6. Flexible 3D CT volume specification.
7. Quantitatively accurate and flexible analytic reconstruction algorithms, i.e., Filtered Backprojection (FBP).
8. Can avoid costly CPU-to-GPU data transfers by performing operations on data already on a GPU.
9. Special-case FBP algorithms that are rarely included in other packages, such as helical, truncated projections, offset detector scan, and Attenuated Radon Transform.
10. Special-case models such as the Attenuated Radon Transform (SPECT and VAM applications) and reconstruction of cylindrically-symmetric objects (flash x-ray applications).
11. Iterative reconstruction algorithms: OSEM, OS-SART, ASD-POCS, RWLS, RDLS, ML-TR, IFBP (RWLS-SARR)
12. Fast multi-GPU 3D densoing methods.
13. Pre-processing algorithms: outlier correction, detector deblur, ring removal, multi-material beam hardening correction (BHC), dual energy decomposition, and SIRZ
14. Easy-to-use, simple API.
15. Easy-to-build executable because the only dependency is CUDA. Python API can be run with or without PyTorch (of course the neural network stuff requires PyTorch).
16. Permissible license.

Physics-based modeling and correction algorithms (e.g., beam hardening correction (BHC), dual energy decomposition, and SIRZ) can be applied when used with the XrayPhysics package.

Installation and Usage

Installation and usage information is posted on the wiki page

Example Results

As a simple demonstration of the accuracy of our projectors we show below the results of FDK reconstructions using ASTRA and LEAP of the walnut CT data. The LEAP reconstruction has 1.7 times higher SNR and reconstructed this data 5.5 times faster than ASTRA.

Future Releases

For the next releases, we are working on the following:

1. Fixes of bugs reported by our users
2. Feature requests from our users
3. More noise reduction filters
4. Physics-based scatter correction

Authors

Kyle Champley ([email protected])

Hyojin Kim ([email protected])

License

LEAP is distributed under the terms of the MIT license. All new contributions must be made under this license. See LICENSE in this directory for the terms of the license. See LICENSE for more details.
SPDX-License-Identifier: MIT
LLNL-CODE-848657

Please cite our work by referencing this github page and citing our article:

Hyojin Kim and Kyle Champley, "Differentiable Forward Projector for X-ray Computed Tomography”, ICML, 2023

leap's Issues

Is the FP and FBP part of the algorithm in LEAP based on ray-driven, pixel-driven, or distance-driven?

curved detector

Hey! Does LEAP handle curved detectors? I am working with medical data and they all have curved detectors so I need software for this.

Different results on CPU and GPU

Hello! I have tested the code and observed that I get different results when forward projecting on the CPU vs the GPU. See the image below. Is this expected behavior?

Code to reproduce:

import torch
from leaptorch import Projector

def main():
    device = torch.device("cuda:0")

    proj = Projector(use_gpu=True, gpu_device=device)

    dimx = 128
    dimy = 128
    dimz = 64
    offsetx = 0
    offsety = 0
    offsetz = 0
    nangles = 180
    nrows = dimz
    ncols = max(dimx, dimy)
    sdd = 1350
    sod = 930
    pheight = sdd/sod
    pwidth = sdd/sod
    width = 1 
    height = 1 
    arange = 180
    crow = 0.5*float(nrows - 1)
    ccol = 0.5*float(ncols - 1)
    phis = torch.arange(0, arange, arange//nangles).float()

    proj.set_volume(dimx=dimx,
                    dimy=dimy,
                    dimz=dimz,
                    width=width,
                    height=height,
                    offsetx=offsetx,
                    offsety=offsety,
                    offsetz=offsetz)

    proj.set_cone_beam(nangles=nangles,
                    nrows=nrows,
                    ncols=ncols,
                    pheight=pheight,
                    pwidth=pwidth,
                    crow=crow,
                    ccol=ccol,
                    arange=arange,
                    phis=phis,
                    sod=sod,
                    sdd=sdd)

    volume = torch.ones((1,64,128,128)).float().to(device)
    volume[..., 40:80, 40:80] = 3.0  # Create a cuboid

    sinogram_gpu = proj(volume)

    device = torch.device("cpu")
    proj_cpu = Projector(use_gpu=False)
    proj_cpu.set_volume(dimx=dimx,
                    dimy=dimy,
                    dimz=dimz,
                    width=width,
                    height=height,
                    offsetx=offsetx,
                    offsety=offsety,
                    offsetz=offsetz)

    proj_cpu.set_cone_beam(nangles=nangles,
                    nrows=nrows,
                    ncols=ncols,
                    pheight=pheight,
                    pwidth=pwidth,
                    crow=crow,
                    ccol=ccol,
                    arange=arange,
                    phis=phis,
                    sod=sod,
                    sdd=sdd)

    sinogram_cpu = proj_cpu(volume.to(device))
    import matplotlib.pyplot as plt

    fig, axs = plt.subplots(1,2)
    axs[0].imshow(sinogram_gpu[0,:,32,:].detach().cpu().numpy())
    axs[0].set_title("GPU")
    axs[1].imshow(sinogram_cpu[0,:,32,:].numpy())
    axs[1].set_title("CPU")
    fig.show()
    fig.savefig("test_diff.jpg")
if __name__ == "__main__":
    main()

import leaptorch error

leapctype.py", line 149, in create_new_model
self.libprojectors.create_new_model.restype = ctypes.c_int
AttributeError: 'NoneType' object has no attribute 'create_new_model'

Is there an official Docker image for LEAP?

Hi,

Thank you for your great CT geometry tools! I am really using well in window system.

So my question is, is there a Docker image to install and run on Linux system?

Although there is a way of installing LEAP on Linux using .sh file, I want to utilize LEAP by using docker image.

Is there any way to make a Docker image for LEAP?

Thanks:)

errors when running demo

I have installed the leapct, but the errors encounter when I run the demo as below:

Can you help me with this issue?

Discrepancy (in Cone-beam geometry) between applying filterProjections then backproject and directly using FBP

Hi,

First of all, thank you for the amazing work!

I'm encountering some discrepancy issue for conebeam geometry. Basically, I tried to filter the projection first and then backproject the filtered projection. However, the results are different from directly calling FBP function (the latter seems to give me correct attenuation coefficient value in reconstruction, but the former was about ~0.1x the correct value). I tried to find what FBP does uniquely, and thought that maybe weightbackprojection was the cause, but even applying weightedbackprojection to filtered projection, the issue was still there. I would really appreciate some help on this.

Here is some part of the code that I use for filter and then backproject:

  projector = leaptorch.Projector(forward_project=False,use_static=False,use_gpu=True,gpu_device=torch.device(device),batch_size=1)
  projector.set_conebeam(numAngles, 
                              numRows, 
                              numCols, 
                              pixelHeight, 
                              pixelWidth, 
                              centerRow, 
                              centerCol, 
                              phis, 
                              sod, 
                              sdd)
  projector.set_volume(numX, numY, numZ, voxelWidth, voxelHeight)
  projector.allocate_batch_data()
  projF = projector.leapct.filterProjections(proj.clone())
  vol = projector(projF)

when trying to use the weightedbackprojector, I replaced the last line of code with this
vol = projector.leapct.weightedBackproject(projF[0], projector.vol_data[0])
But it did not help

encountered an error while running the demo

Merry Christmas !
After installation, I encountered an error while running the code /LEAP/demo_leaptorch/test_fproject_and_FBP.py. How should I handle this?

Traceback (most recent call last):
File "/data4/liqiaoxin/.pycharm_helpers/pydev/pydevconsole.py", line 364, in runcode
coro = func()
File "", line 1, in
File "/data4/liqiaoxin/.pycharm_helpers/pydev/_pydev_bundle/pydev_umd.py", line 198, in runfile
pydev_imports.execfile(filename, global_vars, local_vars) # execute the script
File "/data4/liqiaoxin/.pycharm_helpers/pydev/_pydev_imps/_pydev_execfile.py", line 18, in execfile
exec(compile(contents+"\n", file, 'exec'), glob, loc)
File "/data4/liqiaoxin/code/LEAP/demo_leaptorch/test_fproject_and_FBP.py", line 25, in
from leaptorch import Projector
File "/home/liqiaoxin/anaconda3/envs/pytorch/lib/python3.9/site-packages/leaptorch.py", line 13, in
lct = tomographicModels()
File "/home/liqiaoxin/anaconda3/envs/pytorch/lib/python3.9/site-packages/leapctype.py", line 78, in init
self.libprojectors = cdll.LoadLibrary(os.path.join(current_dir, "../build/lib/libleap.so"))
File "/home/liqiaoxin/anaconda3/envs/pytorch/lib/python3.9/ctypes/init.py", line 460, in LoadLibrary
return self._dlltype(name)
File "/home/liqiaoxin/anaconda3/envs/pytorch/lib/python3.9/ctypes/init.py", line 382, in init
self._handle = _dlopen(self._name, mode)
OSError: /home/liqiaoxin/anaconda3/envs/pytorch/lib/python3.9/site-packages/../build/lib/libleap.so: cannot open shared object file: No such file or directory

Geometry of the cone-beam projection

Hi I tried the cone-beam projection in LEAP, the detector had 200 rows and the centerRow is 100.5 (see below):

proj = Projector(use_gpu=True, gpu_device=device)
proj.leapct.set_volume(256, 256, 100, 1, 1, 0, 0, 0)
proj.leapct.set_conebeam(360, 200, 256, 1, 1.5, 100.5, 128.5, proj.leapct.setAngleArray(360, 360.0), 1000, 1500, tau=0.0, helicalPitch=0.0)
...
sino = proj.leapct.project(sino,img)
plt.imshow(sino[100,:,:].cpu().numpy(), cmap='gray')

However, the displayed projection in the 101 view looks like:

Seems that the parameter of centerRow doesn't work properly?

helical fbp runs slow

Hey! LEAP is soooo impressive! So many features. And it produces great results! Thanks for sharing this with us!! One little problem I have noticed is the helical FBP runs much slower than your other FBP algorithms. I mean the helical projectors are fast but the helical FBP is slow. Is there a reason for this? Can it be faster?

geometric calibration can find centerRow ?

Build error

When I try to install with "pip install ." it fails to build the wheel returning the following error. There seem to be several cases named parallelBeam rather than parallelbeam.

src/main_projector.cpp:606:15: error: ‘class tomographicModels’ as no member named ‘set_parallelBeam’; did you mean ‘set_parallelbeam’?
606 | tempModel.set_parallelBeam(numAngles, numRows, numCols, pixelHeight, pixelWidth, centerRow, centerCol, phis);
| ^~~~~~~~~~~~~~~~
| set_parallelbeam
error: command '/usr/bin/gcc' failed with exit code 1

meet some problem when install LEAP

Hello developer, I want to install the LEAP function library on my X86-linux server. After downloading and changing the current folder with cd, I executed pip install . and encountered an error: ERROR: Could not build wheels for leapct, which is required to install pyproject.toml-based projects. Can you provide a solution?

RWLS not working

Hey! RWLS reconstruction returns all zeros. Could you look into this?

erros when runing demos

I have successfully installed the leapct "pip install ." as below.

But when I run the demo "test_recon_NN.py", the error enconters:

Can you help me with this issue?

Modular geometry

Hello,
Is it possible to use the modular geometry configuration to compute projections pixel-by-pixel independently (Line projection) and combine batches of pixels from different viewing angles? I could not find enough documentation on how to use this option in the library. Could you please share some documentation or an example on this topic?

Thank you in advance.

Best regards,

Total Variation functions do not work for "large" arrays

The Total Variation (TV) functions (cost, gradient quadratic form) do not work for volumes larger than about 1K^3. We are currently working on implementing these algorithms so that they split up the volume into smaller chunks that can be processed on a GPU. We will also make these function compute using multiple GPUs while we are at it.

offsetScan not working?

Helical FBP does not work properly

The helical FBP reconstruction does not work properly and we are currently working on fixing this.