dicomfix

Script and GUI for manipulating dicom plans

$ dicomfix -h
usage: dicomfix [-h] [-w WEIGHTS] [-o OUTPUT] [-a] [-dt] [-ic] [-i] [-ia] [-tr4] [-rs] [-p PRINT_SPOTS]
                [-g GANTRY_ANGLES] [-d DUPLICATE_FIELDS] [-rd RESCALE_DOSE] [-rf RESCALE_FACTOR] [-rm]
                [-tp TABLE_POSITION] [-tt] [-sp SNOUT_POSITION] [-tm TREATMENT_MACHINE] [-pl PLAN_LABEL]
                [-pn PATIENT_NAME] [-rn REVIEWER_NAME] [-rh RANGE_SHIFTER] [-rp REPAINTING]
                [-rl REPEAT_LAYER] [-rld REPEAT_LAYER_DELAY] [-mc] [-ds DUMP_SPOT] [-v] [-V]
                [inputfile]

Modify ECLIPSE DICOM proton therapy treatment plans.

positional arguments:
  inputfile             Input DICOM filename

options:
  -h, --help            show this help message and exit
  -w, --weights WEIGHTS
                        Path to weights CSV file
  -o, --output OUTPUT   Path to output DICOM file
  -a, --approve         Set plan to APPROVED
  -dt, --date           Set RT date to now
  -ic, --intent_curative
                        Set plan intent to CURATIVE
  -i, --inspect         Print a summary of the DICOM file and exit
  -ia, --inspect_all    Print all tags in the DICOM file and exit
  -tr4, --wizard_tr4    Prepare plan for TR4: sets approval, gantry, snout, and treatment machine
  -rs, --fix_raystation
                        Make RayStation plans compatible with Varian proton systems
  -p, --print_spots PRINT_SPOTS
                        Number of random spots to print for comparison
  -g, --gantry_angles GANTRY_ANGLES
                        List of comma-separated gantry angles
  -d, --duplicate_fields DUPLICATE_FIELDS
                        Duplicate all fields in the plan n times
  -rd, --rescale_dose RESCALE_DOSE
                        New rescaled dose [Gy(RBE)]
  -rf, --rescale_factor RESCALE_FACTOR
                        Multiply plan MUs by this factor
  -rm, --rescale_minimize
                        Minimize plan so smallest spot is 1 MU. Overrides the -rd and -rf options.
  -tp, --table_position TABLE_POSITION
                        New table position vertical,longitudinal,lateral [cm]. Use like tp="0,10.5,-5"
                        (important to include the equation mark and quotes)
  -tt, --tolerance_table
                        Add a default IonToleranceTableSequence to the plan. Existing values will be
                        overwritten with a default set.
  -sp, --snout_position SNOUT_POSITION
                        Set new snout position [cm]
  -tm, --treatment_machine TREATMENT_MACHINE
                        Treatment Machine Name
  -pl, --plan_label PLAN_LABEL
                        Set plan label
  -pn, --patient_name PATIENT_NAME
                        Set patient name
  -rn, --reviewer_name REVIEWER_NAME
                        Set reviewer name
  -rh, --range_shifter RANGE_SHIFTER
                        Set range shifter (None, RS2 or RS5) are the only valid options
  -rp, --repainting REPAINTING
                        Repaint each layer multiple times without changing MU.
  -rl, --repeat_layer REPEAT_LAYER
                        Repeat the spot list of each energy layer n times, for depth dose curve scanning. No
                        control points are added, and plan MU and dose grow by n.
  -rld, --repeat_layer_delay REPEAT_LAYER_DELAY
                        Insert a delay spot of this many MU between each pass over a layer, so a stepper has
                        time to move. Requires -rl.
  -mc, --minimize_current
                        Append a 1 MU dummy spot to every energy layer, which forces the cyclotron to the
                        lowest possible beam current.
  -ds, --dump_spot DUMP_SPOT
                        Position of the dump area where the spots dicomfix adds itself are placed, x,y [cm].
                        Applies to both -mc and -rld. Use like -ds="0,14". Default is 14,19.
  -v, --verbosity       Give more output. Option is additive, can be used up to 3 times
  -V, --version         show program's version number and exit

Installation

For development, install in editable mode so source edits take effect immediately:

$ cd ~/Projects/dicomfix
$ pip install -e ".[dev]"    # omit [dev] to skip the test and lint tools
$ dicomfix -h

To make dicomfix available in every shell without activating a virtualenv:

$ uv tool install --editable ~/Projects/dicomfix

Graphical interface

A Qt front-end covers the common operations: rescaling, field duplication, range shifter, treatment machine, gantry angle, table position and snout position.

The GUI needs the gui extra, which dev already includes:

$ pip install -e ".[gui]"     # or ".[dev]", which pulls in gui and web
$ dicomfix-gui                # optionally: dicomfix-gui path/to/plan.dcm

On Windows, download dicomfix-gui-windows-x86_64.zip from the releases page, unpack it, and run dicomfix-gui.exe from the extracted folder — no Python installation needed. Keep that folder together: the executable loads what it needs from the _internal directory beside it, so moving the .exe out on its own will not work.

The Linux archive on that page unpacks the same way, and needs a few Qt system libraries which PyQt6 does not bundle:

$ sudo apt-get install libegl1 libgl1 libxkbcommon-x11-0

Open a plan with File → Open, or drag a DICOM plan anywhere onto the window. Adjust the controls, then press Export. Edits are queued rather than applied as you go, so nothing is written until you export.

The status bar shows the equivalent dicomfix command line for whatever you have queued. The GUI applies edits by running that exact command through the same code path as the CLI, so a plan exported from the GUI is byte-for-byte identical to the same plan produced on the command line — copy the command into a script when you need the operation to be reproducible.

Plan covers the whole plan: approval, intent, date and treatment machine. Field holds the geometry — table position and nozzle, then a divider, then the field selector, gantry and couch, with Copy to all fields to give every field the gantry shown. Wizards covers rescaling, range shifter, field duplication and the RayStation and TR4 fixes.

Two things behave differently from how they may look. Gantry is the only value dicomfix writes per field; table position, nozzle, treatment machine and range shifter are written to every field, even though DICOM stores them per field. If a plan's fields have different table positions, the GUI warns before exporting, because the others would be overwritten.

Controls dicomfix cannot operate are greyed out rather than left inert: the couch angle (there is no way to write PatientSupportAngle), and Approve and Curative Intent on plans already in that state, since neither can be undone. Retract Nozzle sets the snout to its fully retracted position, 42.1 cm.