Struct DicomViewerApp 

pub struct DicomViewerApp {

    pub paths: Paths,
    pub config: Config,
    pub ui_state: UiState,
    pub studies: Vec<Study>,
    pub raw_cache: HashMap<String, Arc<RawImage>>,
    pub raw_failures: HashMap<String, String>,
    pub metadata_cache: HashMap<String, Arc<Vec<TagRow>>>,
    pub metadata_filter: String,
    pub thumbnails: HashMap<String, ThumbnailState>,
    pub grid: GridLayout,
    pub cells: Vec<CellState>,
    pub active_cell: usize,
    pub annotation_store: AnnotationStore,
    pub annotations_path: PathBuf,
    pub last_error: Option<String>,
    pub last_info: Option<String>,
    /* private fields */
}

The single eframe application.

Created by Self::new from main, then handed to [eframe::run_native]. Every per-frame operation goes through the eframe::App::update method below.

Fields

paths: Paths

Resolved data/log/exe paths. See Paths::resolve.

config: Config

Loaded config.toml (or defaults on first run).

ui_state: UiState

Transient UI state — disclaimer/about dialogs, active tool, panel visibility, in-progress measurement, etc.

studies: Vec<Study>

All loaded studies (metadata only; pixels live in Self::raw_cache).

raw_cache: HashMap<String, Arc<RawImage>>

Decoded pixel buffers, keyed by SOP Instance UID. Filled lazily by Self::raw_for; cleared on Self::open_folder.

raw_failures: HashMap<String, String>

SOP UIDs whose decode failed and the reason — so we don’t retry every frame.

metadata_cache: HashMap<String, Arc<Vec<TagRow>>>

Flattened DICOM tag rows for the metadata panel, keyed by SOP UID. Lazily populated by Self::metadata_for.

metadata_filter: String

Substring filter applied to the metadata panel.

thumbnails: HashMap<String, ThumbnailState>

Sidebar previews. Lazily populated one-per-frame so the UI never stalls behind a chain of pixel decodes.

grid: GridLayout

Active grid layout (1×1 up to 4×4).

cells: Vec<CellState>

One CellState per visible viewport cell. Length matches grid.cell_count().

active_cell: usize

Index into Self::cells receiving toolbar actions and keyboard input.

annotation_store: AnnotationStore

Per-SOP-UID annotation list, persisted to a JSON sidecar.

annotations_path: PathBuf

Where Self::annotation_store is loaded from / saved to.

last_error: Option<String>

Last error message — shown in the status bar.

last_info: Option<String>

Last informational message — shown in the status bar.

Implementations

impl DicomViewerApp

pub fn new( cc: &CreationContext<'_>, paths: Paths, config: Config, startup_folder: Option<PathBuf>, ) -> Self

Build the app, install the theme, and load annotations from <data_dir>/annotations.json.

startup_folder defers the actual folder scan to the first update tick so the window paints before the (potentially CD-slow) scan begins.

pub fn save_annotations(&self)

Persist Self::annotation_store to Self::annotations_path. Failures are logged but not propagated — losing one annotation save shouldn’t crash the viewer.

pub fn push_annotation(&mut self, sop_uid: &str, ann: Annotation)

Append ann to the list for sop_uid and immediately save.

pub fn clear_annotations_for_active(&mut self)

Drop every annotation on the instance currently shown by the active cell and immediately save.

pub fn undo_last_annotation_for_active(&mut self)

Remove the most recently pushed annotation on the active cell’s instance and immediately save.

pub fn set_grid(&mut self, g: GridLayout)

Switch grid layout, resizing Self::cells to match. Existing cells are preserved in array order; extras (when shrinking) are truncated. Resets Self::active_cell if it now falls out of range.

pub fn open_folder(&mut self, folder: &Path)

Scan a folder for DICOM files, replace Self::studies, and auto-arrange the first one. Clears every per-instance cache (raw pixels, metadata rows, thumbnails) and every CellState. Errors are surfaced via Self::last_error for the status bar — they’re not propagated to the caller.

pub fn open_file(&mut self, file: &Path)

Convenience: open the parent folder of a single file. We always load a folder — there is no single-file mode.

pub fn select_series(&mut self, study_idx: usize, series_idx: usize)

Click on a series in the sidebar. First tries the MG hanging protocol across the whole study (covers the 4-series-of-1-instance case). If that doesn’t apply, falls back to single-series MG (≥4 instances in this series) or assigning to the active cell.

pub fn try_arrange_mg_study(&mut self, study_idx: usize) -> bool

Look across every MG series in the study and assemble a 2×2 layout when there’s at least one right-breast and one left-breast view.

Placement priority:

1. Strict — RCC, LCC, RMLO, LMLO all present: place in that order.
2. View-known — at least 2 R and 2 L with ViewPosition set: sort each side’s queue by view (CC before MLO) so the top row is the cranio-caudal pair.
3. Laterality-only — at least 2 R and 2 L but ViewPosition is missing (common in some PACS exports): pair in series/instance order.

pub fn drop_series_onto_cell( &mut self, cell_idx: usize, series_ref: (usize, usize), )

Queue a drag-drop assignment. Validated now (so we don’t push garbage), applied next frame (so the cell’s current TextureHandle survives the rest of this frame’s GPU submission).

pub fn raw_for(&mut self, sop_uid: &str, path: &Path) -> Option<Arc<RawImage>>

Get the decoded RawImage for an instance, decoding on first miss. Returns None (and remembers the failure in Self::raw_failures) when decode fails, so the viewport doesn’t re-attempt every frame.

pub fn handle_dropped_files(&mut self, ctx: &Context)

Pick up files dropped onto the egui window. A dropped folder triggers Self::open_folder; a dropped file triggers Self::open_file.

pub fn reset_active_cell(&mut self)

Apply CellState::reset_view to the active cell.

pub fn active_instance(&self) -> Option<&Instance>

Return the instance the active cell is currently showing, if any.

pub fn thumbnail_for(&mut self, series_uid: &str) -> Option<TextureHandle>

Sidebar asks per row: “do you have a thumbnail for this series?” We register a Pending entry on first miss; the per-frame pump in Self::pump_thumbnails decodes one at a time.

pub fn pump_thumbnails(&mut self, ctx: &Context)

Decode at most one pending sidebar thumbnail per frame, so the UI thread isn’t blocked by a long chain of MG-sized decodes.

pub fn metadata_for( &mut self, sop_uid: &str, path: &Path, ) -> Option<Arc<Vec<TagRow>>>

Get the flattened metadata rows for an instance, parsing on first miss. Failures are logged but not cached, since metadata parsing is cheap and unlikely to repeat-fail.

Trait Implementations

impl App for DicomViewerApp

fn update(&mut self, ctx: &Context, _frame: &mut Frame)

Called each time the UI needs repainting, which may be many times per second.

fn on_exit(&mut self)

Called once on shutdown, after [Self::save].

fn save(&mut self, _storage: &mut dyn Storage)

Called on shutdown, and perhaps at regular intervals. Allows you to save state.

fn auto_save_interval(&self) -> Duration

Time between automatic calls to [Self::save]

fn clear_color(&self, _visuals: &Visuals) -> [f32; 4]

Background color values for the app, e.g. what is sent to gl.clearColor.

fn persist_egui_memory(&self) -> bool

Controls whether or not the egui memory (window positions etc) will be persisted (only if the “persistence” feature is enabled).

fn raw_input_hook(&mut self, _ctx: &Context, _raw_input: &mut RawInput)

A hook for manipulating or filtering raw input before it is processed by [Self::update].