Setup and Installation

This page enumerates the steps that must be performed to setup, install and run DEBISim on Linux machines. Provided that the system pre-requisites described below are met, you have installed the third-party modules and have also installed PyQt5, DEBISim can be downloaded, unzipped and run directly for creating virtual bags and their 3D reconstructions. By directly, we mean that there is no need to execute an installation script as long as you are running DEBISim in the same directory where it is downloaded. To take advantage of the GPU support built into DEBISim, it is best to run it in a virtual environment using Anaconda or a Python-based IDE such as PyCharm. Note that all code within the DEBISim package is obfuscated bytecode, i.e., the modules and submodules cannot be read or modified but can be imported by Python scripts running in the same virtual environment. See the Python API Reference for the different DEBISim modules that can be accessed and imported.

System Requirements

DEBISim can be run on Linux/ MacOSx OS machines with limited support on Windows. Proper operation of the software requires the aforementioned third-party modules to be pre-installed on the machine before running DEBISim. Guidelines for installing these have been described ahead.

The system pre-requisites for DEBISim include the following:

Python 2.7.x
CUDA Toolkit (>=v9.2)
For GPU Support: PyTorch (>=v1.0.1), pyGpufit (>=v1.1.0)
The ASTRA toolbox (>=1.9.0)
The FreeCT_wFBP reconstruction package
For GUI Support: PyQT5, pyqtgraph(>=0.10.0) , PyOpenGL (>=3.1.0)

Downloads

DEBISim can be downloaded using one of the following links - make sure that the steps in System Setup have been performed before running the software:

DEBISim==1.2.0: tar.gz, zip

Steps for setting up, installing and running DEBISim are given in the next section.

System Setup

The following steps must be performed in order to use the DEBISim software for data simulation:

DEBISim is built using Python 2.7.x - the Python dependencies for the software can be found here and can be installed as follows:
```
pip install -r requirements.txt
```
Operation of several libraries in DEBISim requires CUDA support (CUDA Toolkit version 9.2 or higher). The software can still be run without CUDA but has limited functionality and takes longer time to run.
ASTRA Toolbox:
- This toolbox is essential for the Forward Model block to work. For use with DEBISim, ASTRA (mostly written in C) needs to be installed from source with Python bindings. Check the ASTRA homepage for Linux installation for instructions on how to install the package in your own machine.
- Make sure that the machine has CUDA (5.5 or higher) installed on it before installing ASTRA.
PyTorch:
- Pytorch is required for accelerated operation using GPUs and can be installed through pip:
```
pip install torch torchvision
```
Gpufit Installation:

PyGpufit is required to speed up the operation of the dual energy decomposition block in the simulation pipeline. This package must be installed and set up as follows:
- Download the Gpufit package from GitHub:
```
git clone https://github.com/gpufit/Gpufit.git Gpufit
```
- Add the files compton_pe.cuh, kn_pe.cuh at the location <path to gpufit>/Gpufit/models/ within the Gpufit directory.
- In the file <path to gpufit>/Gpufit/models/models.cuh, edit the model ID list so that it reads
```
enum ModelID {
    GAUSS_1D = 0,
    GAUSS_2D = 1,
    GAUSS_2D_ELLIPTIC = 2,
    GAUSS_2D_ROTATED = 3,
    CAUCHY_2D_ELLIPTIC = 4,
    LINEAR_1D = 5,
    FLETCHER_POWELL_HELIX = 6,
    BROWN_DENNIS = 7,
    COMPTON_PE = 8
}
```
- Make the same change in the <path to gpufit>/Gpufit/python/pygpufit/gpufit.py so that it reads:
```
class ModelID():
     GAUSS_1D = 0
     GAUSS_2D = 1
     GAUSS_2D_ELLIPTIC = 2
     GAUSS_2D_ROTATED = 3
     CAUCHY_2D_ELLIPTIC = 4
     LINEAR_1D = 5
     COMPTON_PE = 8
```
- Complete the Gpufit installation
```
cd Gpufit
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=RELEASE ../
make
```
- Finish by installing the Python bindings for Gpufit:
```
cd pyGpufit/dist
pip install pyGpufit-X.Y.Z-py2.py3-none-any.whl
```
FreeCT_wFBP:
- Installing this library allows performing fast FBP reconstructions from Spiral CBCT projection data. The installation instructions can be found at the FreeCT_wFBP repository and website.
- To run the example scripts using FreeCT would require the addition of a few filters to the FreeCT library. Copy these filters f_512_sharp.txt, f_512_smooth.txt, f_1024_sharp.txt to the location /usr/local/FreeCT/FreeCT_WFBP/resources/filters/ or whichever path has been assigned to the library. Run sudo make install again to build the library.
GUI Support:
- Running the GUI scripts in Randomized or User-Interactive Mode requires PyQT support for which the libraries can be installed as follows:
```
sudo apt install python-pyqt5 python-pyqt5.opengl
pip install pyqtgraph
```
Additional libraries:

These additional modules are required for I/O operations, data logging and for script obfuscation.
```
pip install astropy tabulate pydicom pyarmor 
```
Environment Setup:

Once the above steps are complete, the DEBISim package can be unzipped and run. As mentioned earlier, since the source code and libraries are obfuscated, they cannot be read or modified but can be imported by Python scripts running within the same virtual environment - see the Python API Reference for the different DEBISim modules that can be accessed and imported. The GUI scripts and examples within the src/scripts/ directory demonstrate how these modules can be used for data simulation. To run the obfuscated scripts, add the path of the DEBISim directory to the PYTHONPATH:
```
export PYTHONPATH=/path/to/debisim/directory:$PYTHONPATH
```

Examples on running the DEBISim simulation pipeline using the simulator modules or by using the GUI are given in Examples and documentation on the same can be found in Documentation.