Skip to content

About

QA reporting tool for a medical particle accelerator — queries Oracle DB, renders diagnostic plots, and exports stamped protocol reports with operator sign-off.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 

Repository files navigation

TH-Tool

TH-Tool

A QA reporting tool for daily QA activities at our medical particle accelerator

Produktion Python GUI Plotting DB Repository


Queries accelerator measurement data from the production Oracle database, structures beam procedures and their cycles, renders multi-panel diagnostic plots, and exports stamped PNG protocol reports and raw CSV data — all approved via operator sign-off.

Note on the private repository: the source code isn't public because it queries a hospital-internal production database and contains institute-specific configuration. This README, along with the screenshots below, serves as a reference for the project's scope and implementation.


Motivation

Before this tool existed, QA protocols for the accelerator ("TH-Protokolle") were assembled largely by hand: graphs had to be manually screenshotted out of a rigid legacy application, resulting in inconsistent documentation across different users and shifts. Deeper analysis of the underlying measurement data required clunky manual exports and separate scripts, and there was no reliable way to track which operator had actually reviewed and approved a given protocol.

TH-Tool replaces that process with a single GUI that queries the accelerator's Oracle database directly, automates the workflow from quality check through archiving, and enforces accountability through named operator sign-off — cutting the time needed to produce a protocol drastically compared to the manual process.


Screenshots

Main Window Intensity Plot Focus Plot Time machine
Main Window Intensity Plot Focus Plot Time machine

Features

  • Procedure browser — hierarchical Treeview of QA sessions with per-step status (complete / partial / data gaps / aborted)
  • Four plot tabs — Intensity, Extraction, Focus, and overview rendered as embedded Matplotlib canvases
  • Graceful missing data — if a diagnostic device fails to record, the tool is capable of detecting it and padding it with NaN arrays so the reamining energy steps stay tick-aligned and the report is still created
  • Sanity checks — particle rates evaluated against ion-specific reference limits (libc_p protons, libc_c) carbon. Failed checks trigger a warning dialog before export
  • Operator sign-off — technician name stamped on all plots before PNG export
  • Dual DB backend — live Oracle production DB or local SQLite replica for offline debugging
  • JSON settings panel — persistent threshold and output-path overrides stores in config.json
  • Release deployment — sync_tool.py strips dev dependencies and inlines .env values for production build

Tech Stack

Layer Library / Tool Role
Language Python 3.8+ Core runtime
GUI Tkinter / ttk Main window, Treeview, Notebook tabs, dialogs
Plotting Matplotlib (FigureCanvasTkAgg) Embedded plot rendering inside Tkinter
Numerics NumPy Data alignment, NaN gap-filling, array math
DB results Pandas (DataFrame) Query result wrapping and tabular CSV export
Production DB cx_Oracle Oracle DB connection (schema bks)
Debug DB sqlite3 (stdlib) Local offline replica (debug_db.sqlite)
Config python-dotenv .env-based connection and path config
Logging loguru Structured, colour-coded runtime logs
Dev tooling reloading Hot-module reload during development
Settings JSON (stdlib) Persistent operator settings (config.json)
Version control Git —

Project Structure

TH-Tool/
├── main.pyw              # Entry point — DPI awareness, icon setup, event loop
├── gui.py                # All Tkinter GUI classes and operator workflows
├── ACSDB.py              # DB abstraction layer (Oracle + SQLite backends)
├── DatabaseStructure.py  # Procedure/sequence models and device config maps
├── Figures.py            # Matplotlib Figure subclasses (Intensity, Focus, Extraction, Additional)
├── sync_tool.py          # Release deployment script (strips dev deps, inlines .env values)
├── debug_db.sqlite       # Local SQLite replica for offline testing
├── config.json           # Persistent runtime settings (thresholds, output paths)
├── .env                  # DB credentials and output path config (not committed)
└── run_debug.bat         # Windows debug launcher

Setup

Prerequisites

  • Python 3.8+
  • Oracle Instant Client (in production mode only)

Install

git clone <repo-url>
cd TH-Tool

python -m venv venv

# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

pip install -r requirements.txt

Configure .env

DB_USER=your_db_user
DB_PWD=your_db_pwassword
DB_NAME=your_db_name
DB_IP=your.oracle.host
PATH_TO_IMGS_RELEASE=C:\path\to\protocol\output\
PATH_TO_IMGS_DEBUG=Strahlprotokolle\

Running

# Debug mode — uses local SQLite, no Oracle required
python main.pyw --debug

# Windows shortcut
run_debug.bat

# Production mode — requires Oracle Instant Client and valid .env
python main.pyw

Procedure State Logic

When a procedure is loaded, its PROC_REPORT_STEPS are evaluated:

State Condition Report export
Complete All STEP_ID=1 sequences have RESULT=1 ✅
Partial Procedure finished; a step was repeated or had a transient error ✅ with warning
Data gaps Procedure complete but one or more devices have no measurement records ✅ with gaps flagged
Aborted One or more sequences did not complete ❌ locked

About

QA reporting tool for a medical particle accelerator — queries Oracle DB, renders diagnostic plots, and exports stamped protocol reports with operator sign-off.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors