A DICOM generator plugin

pl-dicomize is a ChRIS ds plugin that generates DICOM files from existing DICOMs, images, or empty templates. It supports custom DICOM headers, tag copying, and structured reporting sequence headers.

---

Abstract

A ChRIS plugin to generate DICOM files dynamically. Input can be existing DICOMs, images, or empty templates. The plugin allows specifying DICOM headers via JSON, copying tags from existing DICOMs, and configuring SR concept headers.

---

Installation

pl-dicomize is a ChRIS plugin, meaning it can run from either within ChRIS or from the command line using container technologies like Apptainer.

---

Local Usage

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

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

To print its available options, run:

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

Argument	Default	Description
-V, --version	—	Show plugin version
--pattern	"dcm"	File pattern to include (triggers PathMapper on input dir)
--jsonFile	""	Path to JSON file with DICOM header definitions
--tagStruct	""	DICOM headers as a stringified JSON
--copy-tags	""	Comma-separated list of tags to copy from existing DICOMs
--createFrom	"empty"	Generate new DICOM from: dicom, image, or empty
--conceptName	""	Header of concept sequence, required for SR generation

Examples

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

Using Optional Arguments

apptainer exec docker://fnndsc/pl-dicomize:latest dicomize \
    --pattern "dcm" \
    --jsonFile "/path/to/headers.json" \
    --tagStruct '{"PatientName":"Anonymous","StudyDate":"20230101"}' \
    --copy-tags "PatientID,StudyInstanceUID" \
    --createFrom "dicom" \
    --conceptName "MySRConcept" \
    incoming/ outgoing/

Development

Instructions for developers.

Building

Build a local container image:

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

Running

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

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