A ChRIS plugin to verify PACS file registration in CUBE

pl-reg_chxr is a ChRIS ds plugin that waits for a specified set of DICOM files to be registered from a PACS into a CUBE/ChRIS instance. It polls CUBE until the expected data appear, and triggers a downstream processing pipeline.

Abstract

In distributed medical imaging workflows, DICOM data may arrive asynchronously from external PACS systems. Downstream analysis pipelines often require guarantees that all expected studies or series have been fully registered before processing begins.

pl-reg_chxr provides a synchronization and verification step within ChRIS pipelines. Given a JSON description of expected DICOM objects and optional filtering rules, the plugin repeatedly polls CUBE until the required data are available or a configurable timeout is reached. The plugin supports parallel execution, Orthanc/PACS integration, optional anonymization directives, and email notifications.

Installation

pl-reg_chxr 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-reg_chxr as a container:

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

To print its available options, run:

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

Examples

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

Development

Instructions for developers.

Building

Build a local container image:

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

Running

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

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