Skip to content

Getting started

Installation

Set up a new environment with Python 3.10 or higher. We recommend using a virtual environment to avoid conflicts with other packages.

From PyPI

pip install ldct-benchmark

From GitHub

  1. Clone this repository: git clone https://github.com/eeulig/ldct-benchmark
  2. Install the package with pip install .

In editable mode

If you want to implement your own methods or contribute to the project, you should install the package in editable mode using the -eflag:

  1. Clone this repository: git clone https://github.com/eeulig/ldct-benchmark
  2. Install the package with pip install -e .

Dependencies

  • We recommend to install the correct PyTorch version for your operating system and CUDA version from PyTorch directly.
  • [Only if you want to use bilateral] Install the trainable bilateral filter by running pip install bilateralfilter_torch. For details on the bilateral filter see the official repository.

Download the LDCT data

Info

This is only necessary if you want to train or test the models on the LDCT data. If you only want to apply the models to your own data, you can skip this step.

Our benchmark uses the Low Dose CT and Projection data1 which is available from the Cancer Imaging Archive (TCIA). For downloading the data, please follow the instructions below.

1. Sign a TCIA license agreement

You must sign and submit a TCIA Restricted License Agreement to download the data. Information on how to do this is provided under "Data Access" here.

2. Download the LDCT data

Download Version 3 of the LDCT and Projection Data. We provide the .tcia object containing only the Siemens image-domain data (~27 GB) in assets/manifest.tcia.

We provide a script to download all the required data to use the benchmark. Run the following command to download the data to /path/to/datafolder. You must provide your TCIA username and password to access the data:

ldctbench-download-data --savedir /path/to/datafolder --username <username> --password <password>

Info

If your username or password contains special characters, you may need to enclose them in single quotes: 

--username '#!fancy-username' --password 'p@$$w0rd'

Using the NBIA Data Retriever

Ubuntu

After installing the nbia-data-retriever from here, the following command will download the data to /path/to/datafolder: 

/opt/nbia-data-retriever/nbia-data-retriever --cli path/to/repo/assets/manifest.tcia -d /path/to/datafolder -v –f -u <username> -p <password>
with <username> and <password> being your TCIA username/password. Alternatively, you can use the GUI to download using the provided manifest.tcia.

Windows / Mac

After installing the nbia-data-retriever from here use the application to download the data using the provided manifest.tcia. You'll need to provide your TCIA username and password.

3. Set environment variable to the data folder

For training and testing the models on the LDCT data you need to set the environment variable LDCTBENCH_DATAFOLDER to the path of the downloaded data folder. You can do this by running the following command: 

export LDCTBENCH_DATAFOLDER=path/to/ldct-data
where path/to/ldct-data is the path to the downloaded data folder. Alternatively, you can provide the path to the data folder in the config.yaml file for training models or via the argument --datafolder when training/testing models.

  1. McCollough, C., Chen, B., Holmes III, D. R., Duan, X., Yu, Z., Yu, L., Leng, S., & Fletcher, J. (2020). Low Dose CT Image and Projection Data (LDCT-and-Projection-data) (Version 6) [Data set]. The Cancer Imaging Archive. https://doi.org/10.7937/9NPB-2637. ↩