A ChRIS plugin to query a remote PACS

pl-pacs_query is a ChRIS ds plugin that queries a remote PACS using pfdcm and returns structured metadata describing available DICOM studies or series.
The query results are written to the output directory as JSON files for downstream processing.

Abstract

Querying a PACS for available imaging data is a common prerequisite to retrieval and processing workflows.
pl-pacs_query enables automated PACS queries within a ChRIS pipeline by sending directives to a remote PACS via pfdcm and returning the resulting metadata.

The plugin supports configurable PACS endpoints and directives, as well as authentication against a running ChRIS / CUBE instance.

Installation

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

Command-Line Arguments

Positional Arguments

Argument	Description
inputdir	Directory containing input files (read-only). May be empty.
outputdir	Directory where query results will be written.

Optional Arguments

Option	Default	Description
--PACSurl	""	Endpoint URL of the pfdcm service used to communicate with the PACS.
--PACSname	MINICHRISORTHANC	Name of the PACS to query.
--PACSdirective	""	Directive string used to query the PACS (e.g., study- or series-level query).
--CUBEurl	http://localhost:8000/	URL of the CUBE/ChRIS instance (exclude API version).
--CUBEuser	chris	Username for authenticating with CUBE/ChRIS.
--CUBEpassword	chris1234	Password for authenticating with CUBE/ChRIS.

---

Local Usage

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

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

To print its available options, run:

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

Examples

pacs_query 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_query:latest pacs_query [--args] incoming/ outgoing/

Development

Instructions for developers.

Building

Build a local container image:

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

Running

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

docker run --rm -it --userns=host -u $(id -u):$(id -g) \
    -v $PWD/pacs_query.py:/usr/local/lib/python3.12/site-packages/pacs_query.py:ro \
    -v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
    localhost/fnndsc/pl-pacs_query pacs_query /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_query:dev --build-arg extras_require=dev .
docker run --rm -it localhost/fnndsc/pl-pacs_query: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_query:1.2.3 .
docker push docker.io/fnndsc/pl-pacs_query: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_query:1.2.3 chris_plugin_info -d docker.io/fnndsc/pl-pacs_query: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