search

avm-debatr / debisim2

A Python-based 3D CT Simulation library for single and dual energy X-ray image generation. This library is designed to aid in the development and testing of single / dual energy CT based object detectors for airport baggage screening and other CT imaging applications.
https://engineering.purdue.edu/RVL/debisim/html/mainpage.html
GNU General Public License v3.0
9 stars 4 forks source link
baggage-xray computed-tomography simulation x-ray-imaging

readme

DEBISim2.0 - A Simulation Pipeline for Dual Energy CT-based Baggage Inspection Systems

DEBISim (Dual Energy Baggage Image Simulator) is a Python-based 3D CT Simulation library for Single and Dual energy X-ray image data generation. This library is designed to aid in the development, testing and evaluation of Single and Dual Energy CT based target detection systems for airport baggage screening and other CT imaging applications requiring anomaly detection.

The software package presents a simulation pipeline for developing algorithms for baggage inspection scanners and in other similar security screening applications. CT-based target detection systems in general require generating testing and training data by packing and scanning a large number of real bags with real threat materials. Since DEBISim incorporates a complete simulation of physical phenomena involving X-ray transmission, attenuation and detection and also provides a user-configurable scanner geometry, it is an alternative to physically scanning CT baggages for data generation. DEBISim also knows about the wide range of materials (and threat materials) that are encountered in a scanned bag and includes support for simulating them while packing virtual bags.

The DEBISim package includes the following features:

This repository consists of the latest version of our software (DEBISim2.0). The original DEBISim simulator is a Python2-based package which can be downloaded from this link. The complete description of DEBISim, its modules and its usage can be obtained from its official webpage.

DEBISim2.0 is a limited access, open-source version of our simulator which is Python3-based and has the following additional features:

To know more about the mechanism behind the simulator, read our supporting research article: 'DEBISim: A simulation pipeline for dual energy CT-based baggage inspection systems'.

Requirements

Setup and Installation

Download

The code package can be cloned from the git repository using:

git clone https://github.com/avm-debatr/debisim2.git

Before running the simulation scripts, the following steps must be taken for installation:

Anaconda Environment Setup

The conda environment for the code can be created using the environment.yaml file provided with the scripts.

cd debisim2
conda env create --name debienv --file=environment.yaml
conda activate debienv

The following packages need to be downloaded additionally as per the simulation requirements:

ASTRA Toolbox
Gpufit

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:

cd Gpufit
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=RELEASE ../
make
cd pyGpufit/dist
pip install pyGpufit-1.2.0-py2.py3-none-any.whl
FreeCT
Pre-saved models

The pre-saved custom shapes and phantom shape lists can be downloaded from this link into the examples/ directory to run the simulate_ct_phantoms.sh script for phantom simulation.

Simulation examples for different scanner configurations described in configs/ directory can be downloaded from this link into the results/ directory.

Usage

Baggage Simulation

Baggage datasets can be simulated using DEBISim by running the following command:

python run_dataset_generator.py --config=configs/config_default_parallelbeam_2d.py --sim_dir=results/example_default_parallelbeam_2d/ --num_bags=10

The parameters for running the simulation are specifed in a configuration file config.py which provides the details for the scanner setup, the scanner geometry. the X-ray source and the baggage configuration. Examples of config files are provided in the configs/ directory and can be refered to by the user to create their own configurations for baggage simulation.

CT Phantom Simulation

CT Phantoms can be simulated with DEBISim using phantom shape lists provided in examples/ directory. This is done using:

./simulate_ct_phantoms.sh -p acr -o results/simulation_acr/ -s sensation_32

The argument -p specifies the phantom (acr - ACR Medical Scanning Phantom, battelle_a - Battelle A Security Phantom, battelle_b - Battelle B Security Phantom) while the argument -s specifies the scanner used for simulation (sensation_32 | definition_as | force | default).

Artifact Simulation

A new feature in DEBISim2.0 is the generation of second order artifacts. To test the simulation of these artifacts the following script can be run:

./test_simulator_for_artifact_generation.sh -t ring -i results/example_for_artifact_simulation/ -o results/test_ring_artifacts/ -s sensation_32 -z 59

The argument -t specifies the type of artifact (ring - Ring artifacts, motion - Motion artifacts, scatter - Scattering artifacts) while the argument -z specifies the slice to be processed. The argument -i is used to specify the source simulation directory for motion and scatter artifacts.

Ring Artifacts

Scattering Artifacts

The current version of DEBISim 2.0 does not contain the GUI support as in the original DEBISim - to access these, please contact the authors.

Simulation Examples

3D Baggage Image Examples from a Simulated Dataset

A closer Look at the objects spawned within a simulated bag

License

Public Domain, Copyright © 2023, Robot Vision Lab, Purdue University.

Citation

All publications using DEBISim or its datasets must cite the following paper:

@article{manerikar2021debisim,
  title={DEBISim: A simulation pipeline for dual energy CT-based baggage inspection systems}, 
  author={Manerikar, Ankit and Li, Fangda and Kak, Avinash C}, 
  journal={Journal of X-Ray Science and Technology}, 
  volume={29},
  pages={259--285},
  year={2021}
}

Contact

The authors can be contacted at amanerik@purdue.edu (Ankit Manerikar) and li1208@purdue.edu (Fangda Li).