medOS ultra

RT Image-Guided Verification Mini-App

Image-guided verification (IGRT) mini-app for radiation oncology.

12 min readUpdated 2026-05-07docs/architecture/medos-rt-igrt-1-image-guided-verification.md
Field Value
Spec ID medOS-RT-IGRT-1
Status Draft v0.1
Owner Ever Medical Technologies
Module medOS · Radiation Oncology
Companion specs BIA-RT-1 (claim vocabulary), BIA-RT-2 (CarePlan profile), medOS-RT-PlanCockpit
Targets Vajira Hospital, Bunker 1 / Bunker 2 (TrueBeam-class linacs), generalizable to Mosaiq/ARIA-integrated sites
Primary user Radiation Therapist (RTT) at the linac console · in-vault kiosk
Date 2026-05-07

1. Purpose & scope

medOS-RT-IGRT-1 specifies the Image-Guided Verification mini-app: the daily, pre-fraction screen at which a radiation therapist (RTT) reviews today’s verification image (kV-kV pair, CBCT, MV portal, or surface guidance), confirms patient position relative to the planning reference, applies the recommended couch shift, and gates fraction delivery.

This is the highest-volume screen in the RT module — opened ~30 times per patient per course x dozens of patients per day. Its design priorities are: (a) review completable in under two minutes for a routine match, (b) clear escalation path for out-of-tolerance findings, © every action emits a plan event into the cockpit’s event stream, (d) zero-typing kiosk operation in the treatment vault.

This spec covers: the workflow state machine, data model, UX shell, image registration strategy, tolerance and decision logic, adaptive RT trigger thresholds, event payloads, linac/DICOM integration, bilingual operation, and regulatory considerations.

It does not cover: image acquisition itself (handled by linac vendor software), 4D-CBCT motion management (separate spec), surface guidance specifics beyond ingest of position offsets (separate spec).

2. Clinical context

Image-guided radiation therapy (IGRT) is the standard of care for any modulated technique (IMRT/VMAT/SBRT/SRS). Setup uncertainty between the planning CT and daily delivery is corrected by acquiring a verification image in the treatment position and registering it to a reference. The RTT’s task is brief but consequential: a 5 mm uncorrected error on a head-and-neck VMAT plan can shift dose into the spinal cord; a missed anatomy change (weight loss, tumor shrinkage) can require replanning to maintain target coverage.

Modalities supported by this mini-app, in order of clinical frequency at a Thai government tertiary RT department:

  1. kV-CBCT vs planning CT (3D-3D registration) — modulated treatments, daily.
  2. kV-kV orthogonal pair vs DRR (2D-2D) — simple palliation, weekly imaging.
  3. MV portal vs DRR (2D-2D) — fallback / verification.
  4. Surface guidance ingest (SGRT systems: AlignRT, Catalyst HD) — read-only pose offsets, not registration.
  5. MR-linac (out of scope for v0.1; placeholder in data model).

3. User personas & primary task

RTT (primary, kiosk in treatment vault). Given a set up patient, acquires the daily verification image at the linac, then opens this mini-app on a vault-side terminal. Reviews the auto-registration result, accepts or refines, applies the couch shift, and releases the linac for delivery. Target time: <=90 seconds for a routine green match.

Medical Physicist (escalation, console workstation). Called when the RTT escalates an out-of-tolerance match, anatomy concern, or possible replan trigger. Has the same view as the RTT plus access to the underlying registration parameters and history of recent fractions.

Radiation Oncologist (review, web client). Reviews the IGRT history weekly during the OTV; receives push notifications when a ReplanTriggerProposed event fires. Does not normally interact with the IGRT mini-app live.

4. Workflow state machine

States:
  [*] --> AwaitingImage (RTT opens session)
  AwaitingImage --> RegistrationComputing (Image received from linac)
  RegistrationComputing --> AutoRegistered (Auto-reg succeeds)
  RegistrationComputing --> RegistrationFailed (Auto-reg fails)
  AutoRegistered --> ManualAdjustment (RTT refines)
  ManualAdjustment --> AutoRegistered (Reset)
  AutoRegistered --> WithinTolerance (Shift <= green threshold)
  AutoRegistered --> WarningTolerance (Shift > green, <= amber)
  AutoRegistered --> OutOfTolerance (Shift > amber)
  AutoRegistered --> AnatomyConcern (Anatomy check fail)
  WithinTolerance --> Approved (RTT taps Apply)
  WarningTolerance --> Approved (RTT taps Apply, record reason)
  OutOfTolerance --> Escalated (Auto-route to physicist)
  AnatomyConcern --> Escalated (Auto-route)
  RegistrationFailed --> ManualAdjustment (RTT manual reg)
  Escalated --> Approved (Physicist co-sign)
  Escalated --> ReAcquire (Physicist requests new image)
  Escalated --> ReplanProposed (Physicist proposes replan)
  ReAcquire --> AwaitingImage (Setup adjusted)
  Approved --> CouchShiftApplied (Send to linac)
  CouchShiftApplied --> ReadyToDeliver (Final ready)
  ReplanProposed --> [*] (Hold treatment, notify RO)
  ReadyToDeliver --> [*] (Hand off to delivery console)

Each transition emits a plan event (SS10).

5. Data model

igrt_session
  id                              uuid PK
  treatment_plan_id               uuid FK
  phase_id                        uuid FK
  fraction_number                 integer
  state                           enum (states above)
  modality                        enum (kv-cbct | kv-kv | mv-portal | sgrt | mr-linac)
  reference_image_ref             dicom-uid
  daily_image_ref                 dicom-uid
  acquisition_ts                  timestamptz
  registration_method             enum (auto-bone | auto-soft | auto-grey | manual | hybrid)
  shift_lat_mm                    numeric             -- left/right (+L)
  shift_lng_mm                    numeric             -- inf/sup (+S)
  shift_vrt_mm                    numeric             -- ant/post (+A)
  rotation_rtn_deg                numeric             -- yaw / couch rotation
  rotation_pitch_deg              numeric
  rotation_roll_deg               numeric
  shift_magnitude_mm              numeric             -- derived: euclidean of L/L/V
  tolerance_evaluation            enum (within | warning | out-of-tolerance)
  anatomy_qa_pass                 boolean
  anatomy_qa_notes                text
  approver_id                     uuid FK
  approver_role                   enum (rtt | physicist | rt-oncologist)
  cosign_required                 boolean
  cosign_id                       uuid FK
  approved_ts                     timestamptz
  couch_shift_applied_ts          timestamptz
  residual_after_shift            jsonb
  notes                           text
  created_ts                      timestamptz
  created_by                      uuid FK

Linked plan events (SS10) point to this row by igrt_session_id. The session is immutable once approved — corrections after the fact create a new session with a superseded_by_id.

shift_magnitude_mm is the canonical scalar for tolerance evaluation; rotations evaluated separately against degree thresholds.

6. UX shell — kiosk layout

Three-pane viewer plus a decision rail. Designed for a 24"+ touch-capable monitor in the treatment vault, single-glance readable from 1.5 m (RTT often steps back to look at the patient).

+-------------------------------------------------------------------+
| patient strip . plan . FRACTION 13 OF 30 . session timer . escape |
+------------------+------------------+------------------+----------+
|                  |                  |                  | SHIFT    |
|   REFERENCE      |     DAILY        |     FUSION       | TABLE    |
|   (Planning CT   |   (CBCT today)   |  (overlay /      | Lat +1.2 |
|    or DRR)       |                  |   checker /      | Lng -0.8 |
|                  |                  |   diff)          | Vrt +2.1 |
|   PTV / CTV /    |   PTV ghosted    |                  | Rtn +0.4 |
|   OAR contours   |   for ref        |                  | ----------|
|                  |                  |                  | |D| 2.5mm|
|                  |                  |                  | WITHIN   |
|                  |                  |                  | ----------|
|                  |                  |                  | ANAT QA  |
|                  |                  |                  | [APPROVE]|
|                  |                  |                  | [RE-ACQ] |
|                  |                  |                  | [ESCALT] |
+------------------+------------------+------------------+----------+
| tools: W/L pan zoom measure        | view: axial sag cor         |
| mode: bone soft tissue grey manual | blend checker diff          |
+-------------------------------------------------------------------+

Reference pane (left). Planning CT slice with planning structures overlaid: PTV (red), CTV (orange), high-priority OARs (cyan). User scrolls slices via mouse wheel or hardware shuttle.

Daily pane (middle). Today’s verification image at the synchronized slice. Planning structures rendered as ghosted outlines so anatomic discrepancy is visually obvious.

Fusion pane (right). Three modes: overlay blend (slider 0-100%), checkerboard (configurable tile), difference map (signed grayscale). Default is checkerboard 8x8.

Shift / decision rail (right edge, persistent). Six values with per-axis tolerance evaluation, magnitude scalar, anatomy QA checklist, and three primary action buttons.

Tool strip (bottom). Window/level presets, pan, zoom, measurement, crosshair sync. Registration mode selector: bone, soft-tissue, grey-value, manual.

7. Registration strategy

Auto-registration runs first, before the RTT views the panes. Result is presented as the starting position; the RTT can refine.

For 3D-3D (CBCT vs planning CT):

  • Mode bone — rigid, mutual-information cost over a high-pass-filtered intensity volume. Fast (<3 s on commodity GPU). Default for H&N, pelvis, lung, brain.
  • Mode soft-tissue — rigid, mutual-information over a prostate-window-restricted ROI. Slower (~5 s).
  • Mode grey — rigid, normalized mutual information over the full volume. Abdominal sites.
  • Mode manual — RTT drags in viewer panes; shifts update live.

For 2D-2D (kV-kV vs DRR):

  • Orthogonal pair registration with separate AP and Lat shifts; combined into 3D shift via standard geometry.

Implementation. Cornerstone3D’s cornerstone-tools includes registration scaffolding; for the mutual-information cost we extend with a small WASM module (ITK.js or a minimal custom kernel). Full client-side implementation runs in <10 MB and handles air-gapped deployment without round-tripping to a registration server.

Confidence score. Each auto-registration emits a confidence in [0, 1] derived from cost-function landscape sharpness around the optimum. Confidence < 0.7 surfaces a warning chip in the rail and forces an AI Safety Gate review (an AI-derived shift cannot auto-apply below threshold).

8. Tolerance & decision logic

Tolerances are protocol-driven, configured at the plan level (carried in the EverOncologyRTCarePlan profile via a tolerance extension on the phase activity). Default tolerances:

Protocol Translation green Translation warning Translation OOT Rotation green Rotation OOT
H&N IMRT/VMAT <= 3 mm 3-5 mm > 5 mm <= 1 deg > 3 deg
Pelvis IMRT/VMAT <= 5 mm 5-7 mm > 7 mm <= 1 deg > 3 deg
Lung SBRT <= 2 mm 2-3 mm > 3 mm <= 1 deg > 2 deg
Brain SRS <= 1 mm 1-1.5 mm > 1.5 mm <= 0.5 deg > 1 deg
Palliative bone <= 7 mm 7-10 mm > 10 mm <= 3 deg > 5 deg

Decision routing:

  • Within tolerance + anatomy QA pass -> RTT can approve and apply. Single-tap. No co-sign required. Total time goal: 60-90 seconds.
  • Warning + anatomy QA pass -> RTT can approve and apply, but must enter a brief reason recorded as event metadata.
  • Out of tolerance -> action button is disabled; only ESCALATE or RE-ACQUIRE available. Physicist receives push notification.
  • Anatomy QA fail (any axis) -> escalation regardless of shift magnitude.

9. Adaptive RT triggers

Triggers (configurable per protocol):

  1. Cumulative shift drift (last N fractions, default 5) exceeds plan-level tolerance.
  2. Anatomy QA fail repeated on consecutive fractions for the same structure.
  3. CBCT-detected new finding (atelectasis, bowel filling change in pelvis).
  4. RTT or physicist manual flag.

When triggered, the mini-app emits ReplanTriggerProposed with rationale code + supporting session IDs. The Plan Cockpit surfaces this in the Pending panel.

For Vajira pilot: cumulative |D| > 7 mm over 5 consecutive fractions for a H&N IMRT plan = ReplanTriggerProposed. Conservative and tunable.

10. Event payloads (plan event stream)

Every state transition emits an event into the plan’s event log.

// Session opened
{
  "type": "IGRTSessionStarted",
  "treatment_plan_id": "...",
  "phase_id": "...",
  "fraction_number": 13,
  "modality": "kv-cbct",
  "actor_id": "rtt-...",
  "ts": "2026-05-07T09:11:42+07:00"
}

// Auto-registration result
{
  "type": "IGRTRegistrationComputed",
  "session_id": "...",
  "method": "auto-bone",
  "shift_mm": { "lat": 1.2, "lng": -0.8, "vrt": 2.1 },
  "rotation_deg": { "rtn": 0.4, "pitch": 0.1, "roll": -0.2 },
  "magnitude_mm": 2.51,
  "confidence": 0.94,
  "tolerance_evaluation": "within",
  "anatomy_qa": { "parotid": "pass", "cord": "pass", "mandible": "warning" },
  "ts": "..."
}

// Approval
{
  "type": "IGRTApproved",
  "session_id": "...",
  "approver_role": "rtt",
  "approver_id": "...",
  "reason_code": null,
  "ts": "..."
}

// Couch shift sent to linac
{
  "type": "CouchShiftApplied",
  "session_id": "...",
  "applied_shift_mm": { "lat": 1.2, "lng": -0.8, "vrt": 2.1 },
  "applied_rotation_deg": { "rtn": 0.4, "pitch": 0.1, "roll": -0.2 },
  "linac_ack_ts": "...",
  "residual_mm": null,
  "ts": "..."
}

// Escalation
{
  "type": "IGRTEscalated",
  "session_id": "...",
  "escalated_by": "rtt-...",
  "escalated_to": "physicist-...",
  "reason": "anatomy-mandible-warning",
  "ts": "..."
}

// Replan trigger
{
  "type": "ReplanTriggerProposed",
  "session_id": "...",
  "rationale_code": "cumulative-drift",
  "supporting_session_ids": ["...", "...", "...", "...", "..."],
  "proposed_by": "system",
  "ts": "..."
}

11. Linac & DICOM integration

Patient identity at the machine. Modality Worklist (MWL) DIMSE-C-FIND queries the medOS scheduling service for today’s worklist on this machine.

Image arrival. Linac pushes DICOM CT or RT Image objects via DIMSE-C-STORE to Orthanc. Orthanc fires a webhook into the IGRT mini-app, advancing the session from AwaitingImage to RegistrationComputing.

Shift transmission. Approved couch shift sent to linac via:

  • Mosaiq sites — Mosaiq Web Services API or direct SQL.
  • ARIA sites — ARIA Access REST or HL7 ORM^O01 message.
  • Direct linac (no R&V layer) — DICOM-RT BeamsTreatmentRecord or vendor-specific protocol.

RT BeamsTreatmentRecord. After delivery, the linac emits a BeamsTreatmentRecord. medOS ingests via DIMSE-C-STORE and reconciles against the CouchShiftApplied event — any mismatch generates an IGRTReconciliationError event.

12. Bilingual & accessibility

UI strings in both th and en. Default in vault kiosk mode follows linac configuration (Vajira: Thai default). Shift values use Arabic numerals universally. Dose in Gy. Time in 24-hour format.

Minimum 14 pt body text, 11 pt only for ambient meta information. Color is reinforced by shape/text — never the only encoding (accessibility for color-vision-deficient RTTs).

13. Regulatory & safety

The IGRT mini-app is a decision-support component — it does not autonomously deliver radiation.

  • Thai FDA / MDA — Class B medical device software (decision support). ISO 14971 risk analysis; ISO 13485 QMS.
  • US FDA — likely 510(k) Class II.
  • AAPM TG-179 (CBCT IGRT QA), AAPM TG-104 (image-guided RT general guidance).
  • DICOM Conformance Statement required.

Audit-trail: every event (SS10) is immutable and includes actor, timestamp, and (for AI-derived results) the registration method, confidence, and AI Safety Gate status.

14. Performance & failure modes

Performance budget:

  • Image arrival to auto-registration result: < 5 s (CBCT, GPU-accelerated)
  • RTT review for green match: < 90 s (target)
  • Couch shift transmit + ack: < 3 s

Failure modes:

  • Image acquisition fail — no medOS state change.
  • Image transfer fail (DIMSE timeout) — RTT manually re-pushes; medOS stays AwaitingImage.
  • Auto-registration fail — falls through to ManualAdjustment.
  • Linac comms loss on shift transmit — RTT applies shift via linac’s local console and records CouchShiftAppliedManually event.
  • medOS server loss — falls back to local cache mode; events queue locally and reconcile when network returns. RTT may operate against a 30-day-cached patient list.

15. Open questions for v0.2

  • 6DOF couch support. TrueBeam supports it; Versa HD does not. Behavior of roll/pitch rows when machine is 4DOF only?
  • 4D-CBCT motion management. Extension point needed for tumor-motion envelope and gating decisions.
  • Surface guidance fusion. Cross-validate CBCT shift against SGRT pose?
  • Vendor-specific deep links. Open Mosaiq’s image review tool on escalation?
  • Image storage retention. Daily CBCTs accumulate fast (~50 GB/site/year). Retention policy?
  • Replan execution flow. Separate Replan mini-app spec needed.
  • Pediatric tolerances. Tighter; separate protocol set.

16. Implementation notes for medOS

  1. Mini-app shell. Enum value RT_IGRT_COMPARE. Reads treatment_plan_id and fraction_number from URL params, opens or resumes the igrt_session for that fraction.
  2. Cornerstone3D is the rendering substrate. Use vite-react-cornerstone3d template; strip OHIF dependencies.
  3. State machine in XState or Zustand state slices.
  4. Decision rail keyboard bindings. A = Approve, R = Re-acquire, E = Escalate, M = toggle Manual mode, arrow keys = nudge 1 mm, shift+arrow = 0.1 mm.
  5. Audit hooks. Every approval creates a Provenance resource (FHIR R4).
  6. Kiosk mode. Full-screen browser, no tabs, no URL bar, locked to medOS domain.

End of medOS-RT-IGRT-1 v0.1

Ask Anything