A ChRIS plugin to retrieve from a remote PACS

pl-pacs_retrieve is a ChRIS ds plugin that retrieves DICOM images from a remote PACS using pfdcm.
It consumes a JSON file describing DICOM studies or series and retrieves the corresponding DICOM files into the output directory.

Abstract

Medical imaging workflows often require programmatic retrieval of DICOM data from a PACS.
pl-pacs_retrieve enables automated PACS retrieval within a ChRIS pipeline by consuming a JSON description of studies or series and fetching the associated DICOM files via pfdcm.

The plugin supports retrieving individual series defined in a JSON file or optionally retrieving an entire study.

Installation

pl-pacs_retrieve is a ChRIS plugin, meaning it can run from either within ChRIS or the command-line.

Local Usage

To get started with local command-line usage, use Apptainer (a.k.a. Singularity) to run pl-pacs_retrieve as a container:

apptainer exec docker://fnndsc/pl-pacs_retrieve pacs_retrieve [--args values...] input/ output/

To print its available options, run:

apptainer exec docker://fnndsc/pl-pacs_retrieve pacs_retrieve --help

Examples

pacs_retrieve requires two positional arguments: a directory containing input data, and a directory where to create output data. First, create the input directory and move input data into it.

mkdir incoming/ outgoing/
mv some.dat other.dat incoming/
apptainer exec docker://fnndsc/pl-pacs_retrieve:latest pacs_retrieve [--args] incoming/ outgoing/

Development

Instructions for developers.

Building

Build a local container image:

docker build -t localhost/fnndsc/pl-pacs_retrieve .

Running

Mount the source code pacs_retrieve.py into a container to try out changes without rebuild.

docker run --rm -it --userns=host -u $(id -u):$(id -g) \
    -v $PWD/pacs_retrieve.py:/usr/local/lib/python3.12/site-packages/pacs_retrieve.py:ro \
    -v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
    localhost/fnndsc/pl-pacs_retrieve pacs_retrieve /incoming /outgoing

Testing

Run unit tests using pytest. It's recommended to rebuild the image to ensure that sources are up-to-date. Use the option --build-arg extras_require=dev to install extra dependencies for testing.

docker build -t localhost/fnndsc/pl-pacs_retrieve:dev --build-arg extras_require=dev .
docker run --rm -it localhost/fnndsc/pl-pacs_retrieve:dev pytest

Release

Steps for release can be automated by Github Actions. This section is about how to do those steps manually.

Increase Version Number

Increase the version number in setup.py and commit this file.

Push Container Image

Build and push an image tagged by the version. For example, for version 1.2.3:

docker build -t docker.io/fnndsc/pl-pacs_retrieve:1.2.3 .
docker push docker.io/fnndsc/pl-pacs_retrieve:1.2.3

Get JSON Representation

Run chris_plugin_info to produce a JSON description of this plugin, which can be uploaded to ChRIS.

docker run --rm docker.io/fnndsc/pl-pacs_retrieve:1.2.3 chris_plugin_info -d docker.io/fnndsc/pl-pacs_retrieve:1.2.3 > chris_plugin_info.json

Intructions on how to upload the plugin to ChRIS can be found here: https://chrisproject.org/docs/tutorials/upload_plugin