Improve the overall stability of the OHIF viewer, prevent unexplained "blackout screens"

Purpose

This is the umbrella and troubleshooting record for OHIF Viewer failures that leave a blank, black, or white rendering area; remove the surrounding controls; or make the application appear to be stuck. Those symptoms do not have a single root cause, so this issue coordinates the concrete failure and recovery records rather than treating every blackout as the same bug.

User impact

A rendering failure must not strand the user in a viewer with no explanation and no route back to the study list. When only one series fails, successfully loaded study data and the viewer's navigation must remain usable.

Diagnostic evidence to collect

When the symptom occurs, capture:

  1. The full URL and the steps immediately preceding the failure.
  2. A screenshot and, when possible, a screen recording.
  3. The browser developer tools Console with the full error expanded.
  4. The Network tab, including any failed request, its URL, HTTP status, and response body.
  5. The affected study and series identifiers when they can be shared safely.

ohif.blackout-screen

Delivered mitigations

Two distinct MPR blackout failures, both resolved by !58

They present almost identically on screen and are routinely confused. They do not share a cause, and each needed a different part of !58.

  • MPR plane dropout on enlarge/close cycles. One plane (left) goes blank or white immediately after enlarging and closing a plane twice. Caused by a shared render context and resize ordering between MPR and the enlarged inspection view. Fixed by separating those render contexts, firing resize/render from displaySet-API UI events on panel open/close, and rebuilding the inspection view as Cornerstone3DInspectionView. Record: oak-tree/medical-imaging/ohif-viewers#111, with earlier duplicate #102 (closed). Re-run against the Cornerstone3D build and closed 2026-08-05; !58 had recorded it only as a candidate fix, now confirmed.

  • All three MPR planes black after idle. The whole reconstruction goes black after roughly five minutes with the tab backgrounded. Caused by memory pressure in the legacy VTK.js MPR, which held volume data in ad-hoc in-memory objects duplicated per viewport; the browser reclaimed against that footprint and every plane drew from the same evicted data. Fixed by moving the 2D/3D volume cache into the reference-counted Cornerstone3D cache, with single-flighted loading and geometry shared across viewports rather than copied. Record: oak-tree/medical-imaging/ohif-viewers#109.

  • The architecture behind that modernization is documented by oak-tree/medical-imaging/docs/platform!9 (merged) and summarized in the Sonador Cloud 0.4.1 draft release notes.

Remaining behavior and verification

  • A failed study retrieval still needs an explicit Unable to retrieve study data dialog while leaving a usable route out of the viewer.
  • A failed series retrieval still needs an error marker and Unable to retrieve data for series dialog while keeping the top bar and every successfully loaded series visible.
  • The dialog's Details drawer must expose the failed request URL, HTTP status, and response body. That interface and its stale-metadata/incompatible-DICOM verification cases are tracked in oak-tree/medical-imaging/imaging-development-env#69.
  • Aggregation of application logs, user notifications, and series warnings is tracked in oak-tree/medical-imaging/ohif-viewers#84.
  • Study degradation caused by a damaged or incompatible series overlaps oak-tree/medical-imaging/ohif-viewers#80.

Project Tracking

  • OP#140 — historical/pre-migration Viewer Stability reference; it is not present in the current Blueprint instance.
  • OP#137 — current error-aggregation and user-visible recovery tracking.
Edited by Sonador Claude