Skip to content

Downloader-README.md

Latest commit

 

History

History
400 lines (271 loc) · 12.5 KB

Downloader-README.md

File metadata and controls

400 lines (271 loc) · 12.5 KB

DICOM Downloader README

This README provides step-by-step instructions for configuring and using two scripts:

  1. receiver_server.py - A DICOM node receiver server that receives DICOM files from a PACS system
  2. dcm4chee-downloader.py - A script to query a DICOM database and retrieve studies

Table of Contents

Prerequisites

Before using these scripts, ensure you have:

  • Python 3.x installed
  • Required Python packages installed (see requirements.txt)
  • Network access to the PACS server
  • Proper firewall configuration to allow DICOM communication

Script 1: receiver_server.py

The receiver_server.py script acts as a DICOM node receiver server. It listens for incoming DICOM files from a PACS system and stores them in a local directory structure organized by modality and patient ID.

Step 1: Open the Script

Open receiver_server.py in your text editor or IDE.

Step 2: Configure the Required Parameters

Locate the configuration section at the top of the file (lines 16-20) and modify the following four parameters:

# Define the folder to store received DICOM files
STORAGE_FOLDER = "./output/YOUR_DATASET_NAME/"
AE_TITLE = "YOUR AET Title"
LOCAL_IP_ADDRESS = "0.0.0.0"
LOCAL_PORT_NUM = "11112"

Configuration Details:

  1. STORAGE_FOLDER (Line 17)

    • Description: The directory where received DICOM files will be stored
    • Format: A relative or absolute path ending with a forward slash
    • Example: "./output/MY_DATASET/" or "C:/DICOM_Data/MyDataset/"
    • Note: The script will automatically create subdirectories organized by Modality and PatientID

  2. AE_TITLE (Line 18)

    • Description: Your Application Entity Title (AET) - a unique identifier for your DICOM node
    • Format: A string without spaces (typically uppercase)
    • Example: "MY_RECEIVER_AET" or "RH_CANMIC"
    • Important: This must be unique and registered with the database maintainer

  3. LOCAL_IP_ADDRESS (Line 19)

    • Description: The IP address on which the server will listen
    • Options:
      • "0.0.0.0" - Listen on all available network interfaces (recommended)
      • "127.0.0.1" - Listen only on localhost (for testing)
      • Your specific IP address (e.g., "192.168.1.100")
    • Example: "0.0.0.0"

  4. LOCAL_PORT_NUM (Line 20)

    • Description: The port number on which the server will listen for DICOM connections
    • Format: A string containing the port number
    • Example: "11112" or "104"
    • Note: Ensure this port is not already in use and is not blocked by your firewall

Step 3: Inform the Database Maintainer

IMPORTANT: Before running the receiver server, you must inform the database maintainer about the following three configuration values:

  1. AE_TITLE - Your Application Entity Title
  2. LOCAL_IP_ADDRESS - Your server's IP address (if using a specific IP, not 0.0.0.0)
  3. LOCAL_PORT_NUM - The port number your server is listening on

The database maintainer needs this information to configure the PACS system to send DICOM files to your receiver server.

Step 4: Run the Receiver Server

Once configured, run the script:

python receiver_server.py

The server will start and display:

  • Connection status
  • Directory creation messages
  • File storage confirmations as DICOM files are received

Step 5: Verify File Storage

Received DICOM files will be organized in the following structure:

STORAGE_FOLDER/
  └── Modality/
      └── PatientID/
          └── SOPInstanceUID.dcm

Example:

./output/MY_DATASET/
  └── CT/
      └── PATIENT001/
          └── 1.2.840.113619.2.55.3.1234567890.dcm
  └── MR/
      └── PATIENT002/
          └── 1.2.840.113619.2.55.3.0987654321.dcm

Supported DICOM Modalities

The receiver server supports the following DICOM storage SOP classes:

  • CT Image Storage
  • MR Image Storage
  • RT Structure Set Storage
  • Computed Radiography Image Storage
  • Digital X-Ray Image Storage (Presentation and Processing)
  • Secondary Capture Image Storage
  • Positron Emission Tomography Image Storage
  • Enhanced CT Image Storage
  • Enhanced MR Image Storage

Script 2: dcm4chee-downloader.py

The dcm4chee-downloader.py script queries a DICOM database (PACS) and retrieves studies based on query parameters. It uses a C-FIND query to search for studies and a C-MOVE request to retrieve them to your receiver server.

Step 1: Create a .env Configuration File

Create a .env file in the same directory as dcm4chee-downloader.py. This file will contain all the connection and configuration parameters.

Step 2: Configure the .env File

Add the following environment variables to your .env file:

# Your Application Entity Title (must match what you registered with the database maintainer)
CALLING_AET=YOUR_CALLING_AET

# The PACS server's Application Entity Title
CALLED_AET=PACS_SERVER_AET

# The IP address of the PACS server
PACS_IP=192.168.1.100

# The port number of the PACS server (default is 104)
PACS_PORT=104

# The destination folder where DICOM files will be saved (if using local storage)
# OR the AE_TITLE of your receiver_server.py (if using C-MOVE)
DICOM_DESTINATION=./downloaded_dicom/

# Path to the CSV file containing query parameters
QUERY_CSV=./data/query.csv

# The AE_TITLE of your receiver server (must match AE_TITLE in receiver_server.py)
DESTINATION_SERVER_AET=YOUR_RECEIVER_AET

Configuration Details:

  1. CALLING_AET

    • Description: Your Application Entity Title for querying the PACS
    • Example: "MY_QUERY_AET"
    • Note: This should be registered with the database maintainer

  2. CALLED_AET

    • Description: The Application Entity Title of the PACS server you're querying
    • Example: "PACS_SERVER" or "DCM4CHEE"
    • Note: Obtain this from the database maintainer

  3. PACS_IP

    • Description: The IP address or hostname of the PACS server
    • Example: "192.168.1.100" or "pacs.example.com"
    • Note: Ensure you have network access to this address

  4. PACS_PORT

    • Description: The port number the PACS server is listening on
    • Default: 104 (standard DICOM port)
    • Example: "104" or "11113"

  5. DICOM_DESTINATION

    • Description: The destination for retrieved DICOM files
    • Options:
      • Local folder path: "./downloaded_dicom/"
      • Receiver server AE_TITLE: "YOUR_RECEIVER_AET" (recommended when using receiver_server.py)
    • Note: If using C-MOVE, this should be the AE_TITLE of your receiver server

  6. QUERY_CSV

    • Description: Path to the CSV file containing query parameters
    • Example: "./data/query.csv"
    • Note: See Step 3 for CSV file format

  7. DESTINATION_SERVER_AET

    • Description: The AE_TITLE of your receiver server (must match the AE_TITLE in receiver_server.py)
    • Example: "MY_RECEIVER_AET"
    • Note: This is used for C-MOVE requests to send files to your receiver server

Step 3: Create a Query CSV File

Create a CSV file (e.g., data/query.csv) with your query parameters. The file should have two columns: the DICOM tag name and its value.

CSV Format:

QueryRetrieveLevel,STUDY
PatientID,PATIENT001
StudyDate,20240101
AccessionNumber,ACC123456

Common Query Parameters:

  • QueryRetrieveLevel: Usually "STUDY", "SERIES", or "IMAGE"
  • PatientID: Patient identifier
  • StudyDate: Study date (format: YYYYMMDD)
  • AccessionNumber: Accession number
  • Modality: Modality type (CT, MR, PET, etc.)
  • StudyInstanceUID: Specific study UID (if known)

Example CSV file (data/query.csv):

StudyAccessControlID,AETAccessControl
RetrieveAETitle,AET
QueryRetrieveLevel,STUDY

Step 4: Ensure Receiver Server is Running

Before running the downloader script, make sure your receiver_server.py is running and listening for incoming DICOM files. The downloader will use C-MOVE to send files to your receiver server.

Step 5: Run the Downloader Script

Execute the script:

python dcm4chee-downloader.py

Step 6: Monitor the Process

The script will:

  1. Load configuration from the .env file
  2. Read query parameters from the CSV file
  3. Establish an association with the PACS server
  4. Perform a C-FIND query to search for matching studies
  5. Display the number of studies found
  6. Perform C-MOVE requests for each study to transfer them to your receiver server
  7. Release the association

Expected Output:

Association with PACS server established.
Found 5 studies.
Receiving study: 1.2.840.113619.2.55.3.1234567890
Study 1.2.840.113619.2.55.3.1234567890 successfully retrieved.
...
Association released.

Step 7: Verify Downloaded Files

Check your receiver_server.py storage folder (configured in STORAGE_FOLDER) to verify that the DICOM files have been received and organized correctly.

Workflow Overview

The typical workflow for using both scripts together is:

  1. Configure receiver_server.py

    • Set STORAGE_FOLDER, AE_TITLE, LOCAL_IP_ADDRESS, LOCAL_PORT_NUM
    • Inform database maintainer about AE_TITLE, LOCAL_IP_ADDRESS, LOCAL_PORT_NUM

  2. Start receiver_server.py

    • Run the script and keep it running
    • The server will listen for incoming DICOM files

  3. Configure dcm4chee-downloader.py

    • Create .env file with PACS connection details
    • Create query CSV file with search parameters
    • Set DESTINATION_SERVER_AET to match receiver_server.py AE_TITLE

  4. Run dcm4chee-downloader.py

    • The script queries the PACS database
    • Retrieves matching studies using C-MOVE
    • Files are sent to your receiver server

  5. Files are stored

    • Receiver server receives files via C-STORE
    • Files are organized by Modality/PatientID in STORAGE_FOLDER

Troubleshooting

Receiver Server Issues

Problem: Server fails to start

  • Solution: Check if the port is already in use or blocked by firewall
  • Solution: Verify LOCAL_IP_ADDRESS is correct

Problem: No files being received

  • Solution: Verify database maintainer has configured PACS to send to your AE_TITLE, IP, and PORT
  • Solution: Check firewall allows incoming connections on LOCAL_PORT_NUM
  • Solution: Ensure receiver server is running before initiating downloads

Problem: Permission errors when saving files

  • Solution: Check write permissions for STORAGE_FOLDER
  • Solution: Ensure STORAGE_FOLDER path is valid

Downloader Script Issues

Problem: "Failed to associate with the PACS server"

  • Solution: Verify PACS_IP and PACS_PORT are correct
  • Solution: Check network connectivity to PACS server
  • Solution: Verify CALLED_AET matches the PACS server's AE_TITLE
  • Solution: Check firewall allows outbound connections

Problem: "Missing required configuration in .env file"

  • Solution: Verify all required variables are set in .env file
  • Solution: Check for typos in variable names
  • Solution: Ensure .env file is in the same directory as the script

Problem: "No studies found matching the query"

  • Solution: Verify query parameters in CSV file are correct
  • Solution: Check if studies matching the criteria exist in the database
  • Solution: Review query syntax and DICOM tag names

Problem: "Failed to retrieve study"

  • Solution: Verify DESTINATION_SERVER_AET matches receiver_server.py AE_TITLE
  • Solution: Ensure receiver_server.py is running
  • Solution: Check network connectivity between PACS and receiver server

Problem: CSV file not found

  • Solution: Verify QUERY_CSV path in .env is correct
  • Solution: Check file exists and is readable

Additional Notes

  • Security: Keep your .env file secure and do not commit it to version control
  • Network: Ensure proper network configuration for DICOM communication (typically TCP/IP)
  • Performance: Large datasets may take time to transfer; be patient
  • Logging: Monitor console output for status updates and error messages
  • Testing: Test with a small query first before running large batch operations

Support

For issues or questions:

  1. Check the troubleshooting section above
  2. Verify all configuration parameters are correct
  3. Contact the database maintainer for PACS-specific issues
  4. Review DICOM network connectivity and firewall settings