PlanComplexity

Utilities for parsing RT Plan DICOM files and calculating plan complexity metrics across VMAT/IMRT, TOMO, CyberKnife MLC, and Aurora SVMAT plans, with a desktop GUI inspired by UCoMX.

Documentation

Start with the Chinese user guide and complete document index. Editable Markdown/LaTeX guides cover IMRT/VMAT, Halcyon/Ethos, TOMO, CyberKnife MLC, and all Aurora families. The complete equation index maps every catalog record to its formula family. The current Aurora definition is physical geometry with open-aperture conditional means. Historical designs, comparisons and validation runs are explicitly separated from current instructions.

Mode	Current formula version
VMAT/IMRT and CyberKnife MLC	geometry-v4
Halcyon/Ethos canonical Effective/D/P fields	lrt-three-layer-v1
TOMO	tomo-v3
Aurora SVMAT V4	aurora-v5-unified-physical-closure1mm

Requirements

• Python 3.10+
• Packages in requirements.txt

Install dependencies:

python -m pip install -r requirements.txt

Scripts

Launch the desktop GUI:

python ucomx.py

Analyze a single RT Plan file:

python main.py --input-file path/to/plan.dcm

The main analyzer auto-detects VMAT/IMRT, TOMO, CyberKnife MLC, and Aurora SVMAT RTPLAN files.

Aurora exposes 77 metric keys under aurora-v5-unified-physical-closure1mm. All aperture families share real A/B banks, physical layer intersection, jaws and a 1 mm closure mask. Aperture-change rates use mm^2/mm; SAS and small-opening fields share CP fractions and delivered weights; complexity is 1-MCS and CA is P/A. The V5 migration contract describes the changed definitions and local cohort reproduction tools.

Batch export metrics for standard linac plans:

python metrics_mit.py --input-dir path/to/plans --output-csv eclipse.csv

Batch export metrics for Halcyon/Ethos-style plans:

python complexity_metrics_analysis.py --input-dir path/to/plans --output-csv RTPlan1.csv

Halcyon/Ethos dual-layer MLC support includes the paper-specific metrics from Tamura et al. 2020 and Quintero et al. 2021:

• Tamura-style effective 5 mm metrics: MCS5, PA5, PI5, PM5, and EDS.
• Tamura-style weighted layer metrics: MCSw, PAw, PIw, and PMw, with proximal/distal component outputs.
• Quintero-style Halcyon-v2 metrics: MUcp, UL, MCSUL, and NP.
• Hybrid-v2 physical effective-aperture metrics use the *_effective suffix.
• The versioned LRT three-layer interface adds 16 metrics per layer (*_Eff, *_D, *_P), including PI, PM and PR, plus MU, MU_per_CP and the explicit PR_System reference. All 51 fields are exported; the default candidate pool has 50 fields and excludes the duplicate system reference. Historical fields retain their names and calculations. The GUI profile selector displays the candidate pool or each layer separately.
• RT Complexity Lens-inspired stacked diagnostics use the *_stacked suffix. This geometry is deliberately non-physical: it concatenates jaw-evaluated MLCX1 and MLCX2 slots for algorithm comparison and must not be interpreted as a transmitted aperture.

VMAT/IMRT and CyberKnife analyses record metric_formula_version=geometry-v4; TOMO records tomo-v3. The current precision and motion migration, per-metric formula contracts, and TOMO input contract describe units, boundaries, and unavailable results. The preceding hybrid-v2 contract documents the retained MU-weighted MAD/LG/SAS definitions, lt_mean_leaf, explicit leaf counts, and Halcyon representations. The project does not provide an RT_LENS mode or vendor the upstream implementation; independent comparisons may call matteomaspero/rt-complexity-lens directly.

Validation explicitly requests analyze_plan_file(..., full_precision=True); the default VMAT/IMRT and CyberKnife analysis output retains legacy rounding. TOMO and Aurora use their own float paths; TOMO mode estimation retains its binning rule. The external benchmark capture records real UCoMX workbook cells and source/config hashes with its provenance and formula limitations.

The two linac batch scripts accept --recursive for nested folders. The standalone Aurora CLI recursively scans --input-dir by default and has no --recursive flag.

The analysis CLI commands above accept --verbose; documentation and validation tools have their own parser options.

Run the full test suite, including independent numerical hand cases:

python -m pytest tests -q

The GUI tests require a working Tk installation and desktop display. pytest.ini uses Python-stream output capture to avoid intermittent Windows Tcl file-channel failures during repeated GUI creation. The test assertions remain active; see integration and cleanup verification.

Run the Aurora-focused standalone prototype tests:

python -m unittest tests.test_aurora_parser tests.test_aurora_metrics tests.test_aurora_export tests.test_aurora_service tests.test_aurora_gui_smoke -v

Run the research validation gates:

python -m unittest tests.validation.test_validation_smoke tests.validation.test_metric_specs tests.validation.test_spec_loaders tests.validation.test_validation_runtime tests.validation.test_reference_manifest tests.validation.test_freeze_reference_outputs tests.validation.test_reference_suite tests.validation.test_tool_comparison tests.validation.test_validation_report -v

Rebuild the Phase 1 research validation evidence bundle:

python tools/run_formula_oracles.py --output-dir run_reports/validation
python tools/build_paper_reproduction_table.py --output-dir run_reports/validation
python tools/run_reference_suite.py --profile research --output-dir run_reports/validation
python tools/run_tool_comparison.py --profile research --output-dir run_reports/validation
python tools/build_comparator_matrix.py --output-dir run_reports/validation
python tools/build_validation_report.py --profile research --output-dir run_reports/validation
python tools/run_clinical_readiness_gate.py --output-dir run_reports/validation

These commands produce reference_case_results.json, reference_case_results.csv, comparator_statistics.csv, validation_summary.md, validation_report.json, formula_oracles.json, paper_reproduction_table.json, comparator_matrix.json, clinical_readiness_gate.json, supplement_tables/, and manifest_lock.json under run_reports/validation/. The full artifact rebuild requires the referenced RTPLAN files under data/; when running from a separate worktree, pass --source-root path/to/PlanComplexity to point at the data root. The validation bundle is research/publication evidence support and is not clinical deployment ready. The reference command exits nonzero on a failed strict gate, including formula-version or expected support-state mismatches. Scalar baselines have separate formula-version and SHA256 provenance; see the reference pack before updating them.

Optional PSQA/SPC and endpoint association scaffolds are available for institution-approved, de-identified local datasets:

python tools/run_psqa_spc_analysis.py --input-csv psqa_metrics.csv --metric-key mcs --output-dir run_reports/validation
python tools/run_clinical_endpoint_association.py --input-csv endpoints.csv --metric-key mcs --endpoint-key qa_fail --output-dir run_reports/validation

These tools provide harmonization/control-chart and association-only evidence layers. They do not make clinical deployment claims without approved local QA and endpoint data.

Reference Pack v1 details and open-source packaging constraints are documented in docs/reference_pack_v1.md. Clinical implementation controls are documented in docs/clinical_implementation_sop.md and docs/deployment_rollback.md.

Build a standalone Windows GUI executable:

.\.venv\Scripts\python.exe -m pip install PyInstaller
.\tools\build_windows_exe.ps1

The packaged GUI is created at dist\PyUCoMX.exe.

Aurora SVMAT Lab

Aurora SVMAT Lab remains the focused experimental research module for NeuRT Aurora SVMAT RTPLAN analysis. Aurora plan-level metrics are also available through the main PyUCoMX analyzer, GUI, batch CSV export, and AUTO mode alongside VMAT/IMRT, TOMO, and CyberKnife MLC.

Launch the standalone Aurora GUI:

python aurora_svmat.py

Run the standalone Aurora CLI:

python aurora_svmat_cli.py --input-file path/to/RTPLAN.dcm --verbose

Optional Aurora CSV exports:

python aurora_svmat_cli.py --input-file path/to/RTPLAN.dcm --output-csv aurora_plan.csv --beam-output-csv aurora_beams.csv --trajectory-output-csv aurora_trajectory.csv

Aurora prototype scope in the current version:

• Aurora / DeepPlan RTPLAN parsing
• Coupled axial and rotational trajectory reconstruction
• V2 Aurora motion descriptors and engineering proxies (21 keys):
  • longitudinal travel
  • total rotation and rotations
  • travel per rotation
  • projection pitch mean / variability
  • projection MU-density proxy mean / variability
  • projection aperture-change mean / variability
  • projection leaf-travel mean / variability
  • theta-z, MU-z, and MLC-z coupling variability
• V3 peak, regional and dual-layer coordination descriptors (40 keys)
• V4 physical dual-layer aperture descriptors (7 keys): mean_ba, mean_bi, mean_ca, mean_sas5, mean_sas10, mean_mcs_aurora, mcs_complexity_aurora
• All seven V4 means exclude area-zero endpoints and renormalize retained interval weights; SAS and LSV exclude closed gaps. The MCS is an Aurora adaptation, not classic McNiven MCS.
• Legacy engineering metrics (9 keys) are still exported for comparison
• Standalone CSV export and desktop GUI

The Aurora prototype is for research use only. Clinical use is strongly forbidden.

Notes

• The batch scripts now skip unsupported files instead of deleting them.
• Input files are expected to be DICOM RT Plan files readable by pydicom.
• ucomx.py / ucomx_gui.py provide a Python desktop workflow for:
  • VMAT/IMRT analysis using the existing DICOM/aperture metric engine.
  • TOMO analysis using a sinogram-based metric engine built from the UCoMX/TCoMX references.
  • Aurora SVMAT analysis with 77 research/physical-aperture keys and recorded V4 formula version.
  • CyberKnife MLC analysis using the paper-limited six-metric subset (MCS, EM, PI, PM, LG, SAS10).
• The GUI metric panel now uses paper-oriented naming for the two motion metrics discussed below and includes a Metric Notes pane with short definitions.
• The main GUI/service CSV export writes two files (the standalone Aurora CLI has separate plan/beam/trajectory exports):
  • The requested result table, for example results.csv.
  • A companion column dictionary, for example results_columns.csv.
• Folder batch analysis now uses light parallelism for independent RT Plan files, and beam-level geometry/meterset objects are cached during a single-file analysis pass.
• Code paths have been standardized on snake_case module and API naming.
• VMAT/IMRT default formulas use geometry-v4, retaining these hybrid-v2 definitions:
  • MAD is the MU-weighted mean absolute aperture-center distance from the beam central axis.
  • ALG/ALG SD and SAS are calculated per control point and then MU weighted; SAS includes only jaw-overlapping, strictly positive gaps in its denominator.
  • Legacy dose-weighted LT remains unchanged; LT Mean Leaf reports raw trajectory travel per moving physical leaf.
  • Legacy NL remains and equals NL Pairs; NL Leaves is exactly twice that value.
• MLC Speed and Acceleration Proportions (Park 2015) follow:
  • Park JM, et al. Br J Radiol 2015;88(1049):20140698.
  • DOI: 10.1259/bjr.20140698
  • Speed bins in the program are reported in mm/s: 0-4, 4-8, 8-12, 12-16, 16-20.
  • Acceleration bins in the program are reported in mm/s^2: 0-40, 40-80, 80-120, 120-160, 160-200.
  • Each proportion is computed as the mean of per-leaf proportions over valid control-point intervals.
  • These bins require a valid control-point time model. RTPLAN-only exact calculation is unavailable when the plan does not provide usable timing inputs, such as nonzero dose rate, known machine maximum gantry speed, or delivery timestamps.
  • For the current Elekta Monaco/Oncentra RTPLAN exports, CumulativeMetersetWeight is present but DoseRateSet is absent or zero and the machine is identified only by local IDs. In that state the Park speed/acceleration bins are intentionally reported as unavailable/NaN rather than treated as delivery-accurate values.
  • Elekta Park-style values can be added only as explicitly labeled estimates if a site-specific machine profile supplies the missing timing assumptions. Delivery-accurate values require treatment delivery logs or another timestamped machine record.
• SPORT Modulation Index (Li and Xing 2013) follows:
  • Li R, Xing L. Med Phys. 2013;40(5):050701.
  • DOI: 10.1118/1.4802748
  • The implementation keeps the paper's station-wise MI(s) definition and reports the framework's aggregated beam/plan summary for GUI and CSV export.
• CyberKnife MLC mode follows the MLC-based plan-complexity study:
  • Masi L, et al. Med Phys. 2021.
  • DOI: 10.1002/mp.14667
  • The current implementation intentionally covers only the paper's MLC-based scope and reports: MCS, EM, PI, PM, LG, and SAS10.
  • Fixed-cone and Iris collimator plans are not included because their collimation geometry is not dynamically modulated.
• Some TOMO RTPLAN variants store sinogram data in vendor-specific tags. The parser includes standard and private-tag fallbacks, but different Tomo TPS exports may still require additional tag mapping.

Updating documentation artifacts

python tools/export_metric_definitions.py
python -m metric_formula_contracts
python tools/export_aurora_formula_pdf.py
python tools/export_app_summary_pdf.py

Definition Markdown/CSV and the Aurora formula PDF derive from the catalog/contracts and notes. Keep source definitions and generated documents synchronized. The application summary PDF also reads current mode versions and catalog counts. CSVs and patient data remain local and Git-ignored. The documentation audit records scope, historical boundaries and verification.