pacsifier 1.0.0

PACSIFIER: batch DICOM query/retrieve tool for PACS systems

PACSIFIER

PACSIFIER is an open-source tool written in Python to query, retrieve, and edit data in DICOM format from a radiological PACS server. It can be run directly or via a Docker container.

Full documentation: https://translationalml.github.io/pacsifier

Windows users: We strongly recommend using WSL to run PACSIFIER. Linux is the recommended environment.

Quick Start

Option 1: Pre-built Docker Image (Recommended)

Pull the latest release from Quay.io — no cloning, no building, no dependency installation required:

docker pull quay.io/translationalml/pacsifier:latest

Run PACSIFIER:

docker run --rm --net=host \
    -v /path/to/my_dir:/base \
    quay.io/translationalml/pacsifier:latest \
    pacsifier --save --info --queryfile /base/my_query.csv \
    --config /base/my_config.json --out_directory /base/my_output_dir

Tip: You can pin to a specific version (e.g. pacsifier:1.0.0) instead of latest. See available tags on Quay.io.

Or use the convenience Docker wrapper scripts:

pip install pacsifier  # installs the wrapper scripts
docker_pacsifier -c config.json -i -s -q query.csv -d /output

Option 2: Install via pip

pip install pacsifier

Note: When installing via pip, you also need DCMTK installed on your system (sudo apt install dcmtk on Ubuntu).

Features

• Query and retrieve DICOM images from PACS servers
• Move DICOM images between PACS nodes
• Upload DICOM images to PACS servers
• Anonymize DICOM files (directly or via Karnak gateway)
• Get pseudonyms from the De-ID API
• Create DICOMDIR files
• Extract Carestream reports
• Docker wrapper scripts for simplified usage
• Resume interrupted extractions

Usage

PACSIFIER provides several CLI commands. How you run them depends on your installation method:

Install method	How to run commands
Docker (no install)	docker run --rm --net=host quay.io/translationalml/pacsifier:latest pacsifier ...
Docker wrappers (pip install pacsifier)	docker_pacsifier ..., docker_anonymize_dicoms ...
pip / source (pip install pacsifier)	pacsifier ..., pacsifier-anonymize ...

Available commands

Command	Docker wrapper	Description
pacsifier	docker_pacsifier	Query, retrieve, and move DICOM images
pacsifier-anonymize	docker_anonymize_dicoms	Anonymize DICOM files
pacsifier-get-pseudonyms	docker_get_pseudonyms	Get pseudonyms from De-ID API or custom mapping
pacsifier-add-karnak-tags	docker_add_karnak_tags	Tag DICOM files for Karnak de-identification
pacsifier-create-dicomdir	docker_create_dicomdir	Create a DICOMDIR file
pacsifier-move-csv	docker_move_dumps	Move info CSV dumps to a separate folder
pacsifier-extract-carestream-report	docker_extract_carestream_report	Extract text from Carestream SR reports

Common examples

With pip/source install (requires DCMTK on your system):

# Query and save DICOM images locally
pacsifier --save --info -q query.csv -c config.json -d ./output

# Query and move images to a remote DICOM node
pacsifier --move -q query.csv -c config.json

# Upload DICOM images to a PACS server
pacsifier --upload --upload_directory ./dicoms -c config.json

# Resume an interrupted download (skips already downloaded series)
pacsifier --save --resume -q query.csv -c config.json -d ./output

# Anonymize DICOM files
pacsifier-anonymize -d ./data -o ./anonymized --fuzz_acq_dates --remove_private_tags

With Docker (no DCMTK or Python needed):

# Using wrapper scripts (pip install pacsifier for the wrappers only)
docker_pacsifier -c config.json -s -i -q query.csv -d ./output
docker_anonymize_dicoms -d ./data -o ./anonymized -a -p

# Or directly with docker run
docker run --rm --net=host \
    -v /path/to/my_dir:/base \
    quay.io/translationalml/pacsifier:latest \
    pacsifier --save --info -q /base/query.csv -c /base/config.json -d /base/output

Run any command with --help for the full list of options. See Docker Wrappers for more details on the wrapper scripts.

Configuration

Config File

PACSIFIER requires a JSON configuration file:

{
    "server_address": "PACS server IP/URL",
    "port": 4242,
    "server_AET": "SERVER_AET",
    "AET": "YOUR_AET",
    "move_AET": "MOVE_DESTINATION_AET",
    "move_port": 11112,
    "batch_size": 30,
    "batch_wait_time": 10
}

Migrating from PACSMAN

If you are migrating a PACSMAN config.json, update the key names and types:

• server_ip → server_address
• port: string → integer
• move_port: string → integer
• batch_size: string → integer
• batch_wait_time: string → integer

Query File

The query file is a .csv file with columns matching DICOM attributes. Supported columns include: StudyDate, PatientID, SeriesDescription, Modality, ProtocolName, StudyInstanceUID, SeriesInstanceUID, PatientName, PatientBirthDate, AcquisitionDate, DeviceSerialNumber, SeriesNumber, StudyDescription, AccessionNumber, SequenceName, StudyTime, ImageType.

See the full documentation for query file format, examples, and all CLI options.

Documentation

Full documentation is available at https://translationalml.github.io/pacsifier, including:

• Installation Guide
• Command-Line Usage
• Docker Wrappers
• Developer Guide
• API Reference

Building the Documentation

make build-docs

This generates the HTML documentation in docs/_build/html.

Running Tests

Via Docker (recommended)

make build-docker
make test

Locally

Install from Source (For Developers)

git clone https://github.com/TranslationalML/pacsifier.git
cd pacsifier
conda create -n pacsifier_minimal python=3.10
conda activate pacsifier_minimal
pip install -e ".[all]"

Note: Source installations require DCMTK to be installed on your system.

See the full installation guide for all options and details.

Run the tests

See the Developer Guide for instructions on running tests locally with a mock DICOM server.

Contributing

See the Contributing Guide for guidelines on reporting bugs, requesting features, and submitting pull requests.

License

Apache License 2.0. See LICENSE for details.

Citation

If you use PACSIFIER in your work, please cite it. See How to Cite.

Acknowledgments

This project received funding from the Lausanne University Hospital and the Lundin Family Brain Tumour Research Center.