add click-to-inspect frame chart

Author: shrimbly

sharp_frames/ui/screens/selection.py

@@ -9,7 +9,7 @@
 from textual.binding import Binding
 from textual.containers import Container, Horizontal
 from textual.css.query import NoMatches
-from textual.events import Resize
+from textual.events import Click, Resize
 from textual.geometry import Size
 from textual.message import Message
 from textual.reactive import reactive
@@ -27,6 +27,7 @@
 from ...models.frame_data import ExtractionResult, FrameData
 from ...processing.tui_processor import TUIProcessor
 from ..keyboard import OptionSelect, select_focused_option
+from ..utils.image_opener import open_image_file
 
 
 class SharpnessChart(ScrollView):
@@ -50,6 +51,7 @@ class SharpnessChart(ScrollView):
         "sharpness-chart--background",
         "sharpness-chart--selected",
         "sharpness-chart--unselected",
+        "sharpness-chart--inspected",
         "sharpness-chart--title",
     }
 
@@ -84,6 +86,12 @@ class SharpnessChart(ScrollView):
         background: $background;
     }
 
+    SharpnessChart .sharpness-chart--inspected {
+        color: $warning;
+        background: $background;
+        text-style: bold;
+    }
+
     SharpnessChart .sharpness-chart--title {
         color: $primary;
         background: $background;
@@ -100,10 +108,13 @@ def __init__(
         super().__init__(**kwargs)
         self.frames = frames
         self.selected_indices = set(selected_indices or ())
+        self.inspected_index: Optional[int] = None
         self.timeline_width = max(len(frames) * self.FRAME_STRIDE, 1)
         self.virtual_size = Size(self.timeline_width, 1)
         self.border_title = "Frame selection"
-        self.border_subtitle = "Arrows scroll | Ctrl+PgUp/PgDn page | Home/End"
+        self.border_subtitle = (
+            "Click inspect | Arrows scroll | Ctrl+PgUp/PgDn page | Home/End"
+        )
 
         if self.frames:
             scores = [f.sharpness_score for f in self.frames]
@@ -128,6 +139,30 @@ def update_selection(self, selected_indices: set[int]) -> None:
         self.selected_indices = set(selected_indices)
         self.refresh()
 
+    class FrameInspectRequested(Message):
+        """Request that the owning screen open a frame for inspection."""
+
+        def __init__(self, frame: FrameData) -> None:
+            self.frame = frame
+            super().__init__()
+
+    def on_click(self, event: Click) -> None:
+        """Open the frame represented by a clicked chart column."""
+        content_offset = event.get_content_offset(self)
+        if content_offset is None or content_offset.y == 0:
+            return
+
+        virtual_column = int(self.scroll_offset.x) + content_offset.x
+        frame_position = virtual_column // self.FRAME_STRIDE
+        if not 0 <= frame_position < len(self.frames):
+            return
+
+        frame = self.frames[frame_position]
+        self.inspected_index = frame.index
+        self.refresh()
+        self.post_message(self.FrameInspectRequested(frame))
+        event.stop()
+
     def action_first_frame(self) -> None:
         """Scroll directly to the beginning of the analyzed timeline."""
         self.scroll_to(x=0, animate=False)
@@ -182,13 +217,17 @@ def _render_chart_line(
         unselected_style = self.get_component_rich_style(
             "sharpness-chart--unselected"
         )
+        inspected_style = self.get_component_rich_style(
+            "sharpness-chart--inspected"
+        )
         segments = [
             self._render_timeline_column(
                 virtual_column,
                 chart_y,
                 chart_height,
                 selected_style,
                 unselected_style,
+                inspected_style,
                 blank_style,
             )
             for virtual_column in range(
@@ -205,6 +244,7 @@ def _render_timeline_column(
         chart_height: int,
         selected_style: Style,
         unselected_style: Style,
+        inspected_style: Style,
         blank_style: Style,
     ) -> Segment:
         """Render a bar column or the blank gap following it."""
@@ -218,11 +258,12 @@ def _render_timeline_column(
         if glyph == " ":
             return Segment(" ", blank_style)
 
-        style = (
-            selected_style
-            if frame.index in self.selected_indices
-            else unselected_style
-        )
+        if frame.index == self.inspected_index:
+            style = inspected_style
+        elif frame.index in self.selected_indices:
+            style = selected_style
+        else:
+            style = unselected_style
         return Segment(glyph, style)
 
     @classmethod
@@ -574,6 +615,27 @@ def compose(self) -> ComposeResult:
 
         yield Footer()
 
+    async def on_sharpness_chart_frame_inspect_requested(
+        self, event: SharpnessChart.FrameInspectRequested
+    ) -> None:
+        """Open a clicked frame in the platform's default image viewer."""
+        frame = event.frame
+        try:
+            await asyncio.to_thread(open_image_file, frame.path)
+        except (FileNotFoundError, OSError) as exc:
+            self.notify(
+                str(exc),
+                title="Unable to inspect frame",
+                severity="error",
+            )
+            return
+
+        self.notify(
+            f"Frame {frame.index + 1:,} · sharpness {frame.sharpness_score:.2f}",
+            title="Opened image",
+            timeout=3,
+        )
+
     def _frame_count_summary(self) -> str:
         """Summarize analyzed and excluded inputs for the title row."""
         analyzed_count = len(self.extraction_result.frames)
@@ -730,7 +792,8 @@ def action_help(self) -> None:
 1. **Choose a method** from the dropdown
 2. **Adjust parameters** as needed 
 3. **Watch the count update** in real-time as you change settings
-4. **Press "Process"** when you're happy with the selection
+4. **Click a chart bar** to inspect that image in your default viewer
+5. **Press "Process"** when you're happy with the selection
 
 The preview count updates instantly as you make changes, so you can experiment freely!
 

sharp_frames/ui/utils/image_opener.py

@@ -0,0 +1,33 @@
+"""Open analyzed frame images with the platform's default viewer."""
+
+import os
+import platform
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+def open_image_file(path: str, system_name: Optional[str] = None) -> None:
+    """Open an existing image without blocking the Textual application."""
+    image_path = Path(path).expanduser()
+    if not image_path.is_file():
+        raise FileNotFoundError(f"Frame image is no longer available: {image_path}")
+
+    current_system = system_name or platform.system()
+    if current_system == "Windows":
+        startfile = getattr(os, "startfile", None)
+        if startfile is None:
+            raise OSError("Windows image opener is unavailable")
+        startfile(str(image_path))
+        return
+
+    command = ["open", str(image_path)] if current_system == "Darwin" else [
+        "xdg-open",
+        str(image_path),
+    ]
+    subprocess.Popen(
+        command,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )

tests/ui/test_selection_screen.py

@@ -245,6 +245,64 @@ def compose(self) -> ComposeResult:
         assert chart.scroll_offset.x == 0
 
 
+@pytest.mark.asyncio
+async def test_clicking_chart_bar_requests_frame_inspection():
+    frames = [
+        FrameData(f"/tmp/frame_{index:05d}.jpg", index, float(index + 1))
+        for index in range(100)
+    ]
+    chart = SharpnessChart(frames)
+
+    class ChartApp(App):
+        CSS = SHARP_FRAMES_CSS
+
+        def __init__(self):
+            super().__init__()
+            self.inspected = []
+
+        def compose(self) -> ComposeResult:
+            yield chart
+
+        def on_sharpness_chart_frame_inspect_requested(self, event):
+            self.inspected.append(event.frame)
+
+    app = ChartApp()
+    async with app.run_test(size=(80, 24)) as pilot:
+        await pilot.pause()
+        await pilot.click(chart, offset=(1, 2))
+        await pilot.pause()
+
+        assert app.inspected == [frames[0]]
+        assert chart.inspected_index == frames[0].index
+
+        chart.scroll_to(x=SharpnessChart.FRAME_STRIDE * 2, animate=False)
+        await pilot.pause()
+        await pilot.click(chart, offset=(1, 2))
+        await pilot.pause()
+
+        assert app.inspected[-1] == frames[2]
+        assert chart.inspected_index == frames[2].index
+
+
+@pytest.mark.asyncio
+async def test_frame_inspection_handler_opens_analyzed_path(screen):
+    frame = screen.extraction_result.frames[3]
+    event = SimpleNamespace(frame=frame)
+
+    with (
+        patch(
+            "sharp_frames.ui.screens.selection.asyncio.to_thread",
+            new=AsyncMock(),
+        ) as to_thread,
+        patch.object(screen, "notify") as notify,
+    ):
+        await screen.on_sharpness_chart_frame_inspect_requested(event)
+
+    to_thread.assert_awaited_once()
+    assert to_thread.await_args.args[1] == frame.path
+    assert notify.call_args.kwargs["title"] == "Opened image"
+
+
 def test_input_with_controls_retains_value_before_mount():
     control = InputWithControls(
         value="5", input_id="batch-size", min_value=1, max_value=10

tests/ui/utils/test_image_opener.py

@@ -0,0 +1,45 @@
+"""Tests for opening analyzed frames in a platform viewer."""
+
+from unittest.mock import patch
+
+import pytest
+
+from sharp_frames.ui.utils.image_opener import open_image_file
+
+
+def test_macos_uses_default_open_command(tmp_path):
+    image = tmp_path / "frame with spaces.jpg"
+    image.touch()
+
+    with patch("sharp_frames.ui.utils.image_opener.subprocess.Popen") as popen:
+        open_image_file(str(image), system_name="Darwin")
+
+    assert popen.call_args.args[0] == ["open", str(image)]
+    assert popen.call_args.kwargs["start_new_session"] is True
+
+
+def test_linux_uses_xdg_open(tmp_path):
+    image = tmp_path / "frame.jpg"
+    image.touch()
+
+    with patch("sharp_frames.ui.utils.image_opener.subprocess.Popen") as popen:
+        open_image_file(str(image), system_name="Linux")
+
+    assert popen.call_args.args[0] == ["xdg-open", str(image)]
+
+
+def test_windows_uses_startfile(tmp_path):
+    image = tmp_path / "frame.jpg"
+    image.touch()
+
+    with patch(
+        "sharp_frames.ui.utils.image_opener.os.startfile", create=True
+    ) as startfile:
+        open_image_file(str(image), system_name="Windows")
+
+    startfile.assert_called_once_with(str(image))
+
+
+def test_missing_frame_reports_that_temp_file_is_unavailable(tmp_path):
+    with pytest.raises(FileNotFoundError, match="no longer available"):
+        open_image_file(str(tmp_path / "missing.jpg"), system_name="Darwin")