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.
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.
| Main Window | Intensity Plot | Focus Plot | Time machine |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
- 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
NaNarrays 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_pprotons,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.pystrips dev dependencies and inlines.envvalues for production build
| 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 | — |
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
- Python 3.8+
- Oracle Instant Client (in production mode only)
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.txtDB_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\# 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.pywWhen 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 |



