canns 0.13.1__py3-none-any.whl → 0.14.0__py3-none-any.whl

canns/pipeline/asa_gui/views/widgets/gridscore_tab.py

@@ -0,0 +1,308 @@
+"""GridScore result viewer tab."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import (
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QSpinBox,
+    QSplitter,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .image_viewer import ImageViewer
+from .popup_combo import PopupComboBox
+
+
+class GridScoreTab(QWidget):
+    """GridScore viewer with distribution and neuron inspector."""
+
+    inspectRequested = Signal(int, dict)
+
+    def __init__(self, title: str = "Grid Score") -> None:
+        super().__init__()
+        self.title = title
+
+        self._npz_path: Path | None = None
+        self._meta: dict[str, Any] = {}
+        self._ids: np.ndarray | None = None
+        self._scores: np.ndarray | None = None
+        self._spacing: np.ndarray | None = None
+        self._orientation: np.ndarray | None = None
+        self._id_to_idx: dict[int, int] = {}
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(0, 0, 0, 0)
+
+        splitter = QSplitter(Qt.Vertical)
+        root.addWidget(splitter, 1)
+
+        # Distribution panel
+        dist = QWidget()
+        dist_layout = QVBoxLayout(dist)
+        dist_layout.setContentsMargins(8, 8, 8, 8)
+        self.dist_header = QLabel("Grid score distribution")
+        self.dist_header.setStyleSheet("font-weight: 600;")
+        dist_layout.addWidget(self.dist_header)
+
+        self.dist_viewer = ImageViewer()
+        dist_layout.addWidget(self.dist_viewer, 1)
+
+        splitter.addWidget(dist)
+
+        # Inspector panel
+        insp = QWidget()
+        insp_layout = QVBoxLayout(insp)
+        insp_layout.setContentsMargins(8, 8, 8, 8)
+
+        self.insp_header = QLabel("Neuron inspector")
+        self.insp_header.setStyleSheet("font-weight: 600;")
+        insp_layout.addWidget(self.insp_header)
+
+        ctrl = QHBoxLayout()
+        self.btn_prev = QPushButton("◀")
+        self.btn_next = QPushButton("▶")
+        self.neuron_id = QSpinBox()
+        self.neuron_id.setRange(0, 0)
+        self.neuron_id.setValue(0)
+        self.sort_combo = PopupComboBox()
+        self.sort_combo.addItems(
+            [
+                "neuron id (asc)",
+                "neuron id (desc)",
+                "grid score (desc)",
+                "grid score (asc)",
+            ]
+        )
+        self.btn_show = QPushButton("Show neuron")
+
+        ctrl.addWidget(QLabel("neuron_id:"))
+        ctrl.addWidget(self.btn_prev)
+        ctrl.addWidget(self.neuron_id)
+        ctrl.addWidget(self.btn_next)
+        ctrl.addSpacing(8)
+        ctrl.addWidget(QLabel("sort:"))
+        ctrl.addWidget(self.sort_combo)
+        ctrl.addStretch(1)
+        ctrl.addWidget(self.btn_show)
+        insp_layout.addLayout(ctrl)
+
+        self.lbl_metrics = QLabel("grid_score: —    spacing: —    orientation: —")
+        self.lbl_metrics.setStyleSheet("font-family: Menlo, Consolas, monospace;")
+        insp_layout.addWidget(self.lbl_metrics)
+
+        self.auto_viewer = ImageViewer()
+        insp_layout.addWidget(self.auto_viewer, 1)
+
+        self.lbl_status = QLabel("")
+        self.lbl_status.setStyleSheet("color: #666;")
+        insp_layout.addWidget(self.lbl_status)
+
+        splitter.addWidget(insp)
+        splitter.setStretchFactor(0, 1)
+        splitter.setStretchFactor(1, 2)
+
+        self.btn_prev.clicked.connect(lambda: self._shift(-1))
+        self.btn_next.clicked.connect(lambda: self._shift(+1))
+        self.neuron_id.valueChanged.connect(self._on_neuron_changed)
+        self.sort_combo.currentIndexChanged.connect(self._on_sort_changed)
+        self.btn_show.clicked.connect(self._emit_inspect)
+
+        self.set_enabled(False)
+
+    def set_enabled(self, enabled: bool) -> None:
+        self.btn_prev.setEnabled(enabled)
+        self.btn_next.setEnabled(enabled)
+        self.neuron_id.setEnabled(enabled)
+        self.sort_combo.setEnabled(enabled)
+        self.btn_show.setEnabled(enabled)
+
+    def clear(self) -> None:
+        self._npz_path = None
+        self._meta = {}
+        self._ids = None
+        self._scores = None
+        self._spacing = None
+        self._orientation = None
+        self._id_to_idx = {}
+        self._order_ids: list[int] = []
+        self._order_index: dict[int, int] = {}
+        self._current_order_pos = 0
+        self.dist_header.setText("Grid score distribution")
+        self.insp_header.setText("Neuron inspector")
+        self.lbl_metrics.setText("grid_score: —    spacing: —    orientation: —")
+        self.lbl_status.setText("")
+        self.dist_viewer.set_image(None)
+        self.auto_viewer.set_image(None)
+        self.neuron_id.setRange(0, 0)
+        self.neuron_id.setValue(0)
+        self.set_enabled(False)
+
+    def set_distribution_image(self, path: Path | None) -> None:
+        if path is not None:
+            self.dist_header.setText(f"{self.title} — {path.name}")
+        else:
+            self.dist_header.setText(f"{self.title} — (no figure)")
+        self.dist_viewer.set_image(path)
+
+    def load_gridscore_npz(self, path: Path) -> None:
+        self._npz_path = path
+        data = np.load(str(path), allow_pickle=True)
+
+        self._meta = {}
+        for k in (
+            "neuron_start",
+            "neuron_end",
+            "bins",
+            "min_occupancy",
+            "smoothing",
+            "sigma",
+            "overlap",
+            "mode",
+        ):
+            if k in data:
+                v = data[k]
+                try:
+                    self._meta[k] = v.item() if hasattr(v, "item") else v
+                except Exception:
+                    self._meta[k] = v
+
+        if "grid_score" in data:
+            self._scores = np.asarray(data["grid_score"])
+        elif "score" in data:
+            self._scores = np.asarray(data["score"])
+        else:
+            self._scores = None
+
+        self._spacing = np.asarray(data["spacing"]) if "spacing" in data else None
+        self._orientation = np.asarray(data["orientation"]) if "orientation" in data else None
+
+        if "neuron_ids" in data:
+            self._ids = np.asarray(data["neuron_ids"]).astype(int)
+        else:
+            ns = int(self._meta.get("neuron_start", 0))
+            ne = int(
+                self._meta.get(
+                    "neuron_end",
+                    ns + (len(self._scores) if self._scores is not None else 1),
+                )
+            )
+            self._ids = np.arange(ns, ne, dtype=int)
+
+        self._id_to_idx = {int(nid): int(i) for i, nid in enumerate(self._ids.tolist())}
+
+        if self._ids.size > 0:
+            mn = int(self._ids.min())
+            mx = int(self._ids.max())
+            self.neuron_id.setRange(mn, mx)
+            self.set_enabled(True)
+            self._apply_sort(preserve_id=mn)
+            self.lbl_status.setText(f"Loaded {len(self._ids)} neurons from {path.name}")
+        else:
+            self.set_enabled(False)
+            self.lbl_status.setText("No neurons found in gridscore.npz")
+
+    def has_scores(self) -> bool:
+        return self._scores is not None and self._ids is not None and len(self._id_to_idx) > 0
+
+    def get_meta_params(self) -> dict[str, Any]:
+        return dict(self._meta) if isinstance(self._meta, dict) else {}
+
+    def set_autocorr_image(self, path: Path | None) -> None:
+        self.auto_viewer.set_image(path)
+
+    def set_status(self, msg: str) -> None:
+        self.lbl_status.setText(msg)
+
+    def _shift(self, step: int) -> None:
+        if not self.neuron_id.isEnabled():
+            return
+        if not self._order_ids:
+            self.neuron_id.setValue(self.neuron_id.value() + int(step))
+            return
+        new_pos = self._current_order_pos + int(step)
+        new_pos = max(0, min(len(self._order_ids) - 1, new_pos))
+        self._current_order_pos = new_pos
+        self.neuron_id.setValue(int(self._order_ids[new_pos]))
+
+    def _on_neuron_changed(self, nid: int) -> None:
+        if not self.has_scores():
+            self.lbl_metrics.setText("grid_score: —    spacing: —    orientation: —")
+            return
+        nid = int(nid)
+        if self._order_index:
+            self._current_order_pos = self._order_index.get(nid, self._current_order_pos)
+        idx = self._id_to_idx.get(nid)
+        if idx is None:
+            self.lbl_metrics.setText("grid_score: —    spacing: —    orientation: —")
+            return
+
+        score = float(self._scores[idx]) if self._scores is not None else float("nan")
+
+        spc_txt = "—"
+        if self._spacing is not None and self._spacing.ndim >= 2:
+            spc = self._spacing[idx][:3]
+            spc_txt = f"{spc[0]:.2f}, {spc[1]:.2f}, {spc[2]:.2f}"
+
+        ori_txt = "—"
+        if self._orientation is not None and self._orientation.ndim >= 2:
+            ori = self._orientation[idx][:3]
+            ori_txt = f"{ori[0]:.1f}, {ori[1]:.1f}, {ori[2]:.1f}"
+
+        self.lbl_metrics.setText(
+            f"grid_score: {score:.3f}    spacing: {spc_txt}    orientation: {ori_txt}"
+        )
+
+    def _on_sort_changed(self) -> None:
+        if not self.has_scores():
+            return
+        self._apply_sort(preserve_id=int(self.neuron_id.value()))
+
+    def _apply_sort(self, preserve_id: int | None = None) -> None:
+        if self._ids is None:
+            return
+        ids = [int(nid) for nid in self._ids.tolist()]
+        scores = None
+        if self._scores is not None:
+            try:
+                scores = [float(s) for s in self._scores.tolist()]
+            except Exception:
+                scores = None
+
+        mode = self.sort_combo.currentText()
+        if mode == "neuron id (desc)":
+            order_ids = sorted(ids, reverse=True)
+        elif mode == "grid score (asc)" and scores is not None:
+            order_ids = [i for i, _ in sorted(zip(ids, scores, strict=False), key=lambda t: t[1])]
+        elif mode == "grid score (desc)" and scores is not None:
+            order_ids = [
+                i
+                for i, _ in sorted(zip(ids, scores, strict=False), key=lambda t: t[1], reverse=True)
+            ]
+        else:
+            order_ids = sorted(ids)
+
+        self._order_ids = order_ids
+        self._order_index = {nid: idx for idx, nid in enumerate(order_ids)}
+
+        if preserve_id is None or preserve_id not in self._order_index:
+            preserve_id = order_ids[0] if order_ids else None
+
+        if preserve_id is not None:
+            self._current_order_pos = self._order_index.get(preserve_id, 0)
+            self.neuron_id.setValue(int(preserve_id))
+
+    def _emit_inspect(self) -> None:
+        if not self.has_scores():
+            return
+        nid = int(self.neuron_id.value())
+        meta = self.get_meta_params()
+        meta["neuron_id"] = nid
+        self.inspectRequested.emit(nid, meta)

canns/pipeline/asa_gui/views/widgets/help_dialog.py

@@ -0,0 +1,27 @@
+"""Help dialog widget."""
+
+from __future__ import annotations
+
+from PySide6.QtWidgets import QDialog, QDialogButtonBox, QTextBrowser, QVBoxLayout
+
+
+class HelpDialog(QDialog):
+    def __init__(self, title: str, markdown: str, parent=None) -> None:
+        super().__init__(parent)
+        self.setWindowTitle(title)
+        self.resize(680, 520)
+
+        layout = QVBoxLayout(self)
+        browser = QTextBrowser()
+        browser.setOpenExternalLinks(True)
+        browser.setMarkdown(markdown)
+        layout.addWidget(browser)
+
+        buttons = QDialogButtonBox(QDialogButtonBox.Close)
+        buttons.rejected.connect(self.reject)
+        layout.addWidget(buttons)
+
+
+def show_help_dialog(parent, title: str, markdown: str) -> None:
+    dialog = HelpDialog(title=title, markdown=markdown, parent=parent)
+    dialog.exec()

canns/pipeline/asa_gui/views/widgets/image_tab.py

@@ -0,0 +1,50 @@
+"""Image tab widget."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtCore import QUrl
+from PySide6.QtGui import QDesktopServices
+from PySide6.QtWidgets import QHBoxLayout, QLabel, QPushButton, QVBoxLayout, QWidget
+
+from .image_viewer import ImageViewer
+
+
+class ImageTab(QWidget):
+    def __init__(self, title: str) -> None:
+        super().__init__()
+        self._title = title
+        self._path: Path | None = None
+
+        layout = QVBoxLayout(self)
+        header_row = QHBoxLayout()
+        self._header = QLabel(title)
+        self._header.setStyleSheet("font-weight: 600;")
+        header_row.addWidget(self._header)
+        header_row.addStretch(1)
+        self._btn_open = QPushButton("Open Image")
+        self._btn_open.setEnabled(False)
+        self._btn_open.clicked.connect(self._open_image)
+        header_row.addWidget(self._btn_open)
+        layout.addLayout(header_row)
+
+        self.viewer = ImageViewer()
+        layout.addWidget(self.viewer, 1)
+
+    def set_image(self, path: Path | str | None) -> None:
+        if path is None:
+            self._header.setText(self._title)
+            self._path = None
+            self._btn_open.setEnabled(False)
+        else:
+            path = Path(path)
+            self._header.setText(f"{self._title} — {path.name}")
+            self._path = path
+            self._btn_open.setEnabled(path.exists())
+        self.viewer.set_image(path)
+
+    def _open_image(self) -> None:
+        if self._path is None or not self._path.exists():
+            return
+        QDesktopServices.openUrl(QUrl.fromLocalFile(str(self._path)))

canns/pipeline/asa_gui/views/widgets/image_viewer.py

@@ -0,0 +1,97 @@
+"""Image viewer widget with zoom and pan."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtCore import QPointF, QRectF, Qt
+from PySide6.QtGui import QColor, QPainter, QPixmap
+from PySide6.QtWidgets import QGraphicsPixmapItem, QGraphicsScene, QGraphicsTextItem, QGraphicsView
+
+
+class ImageViewer(QGraphicsView):
+    """Image viewer with fit-to-view, zoom (wheel), and pan (drag)."""
+
+    def __init__(self, parent=None) -> None:
+        super().__init__(parent)
+        self.setRenderHints(QPainter.Antialiasing | QPainter.SmoothPixmapTransform)
+        self.setTransformationAnchor(QGraphicsView.AnchorUnderMouse)
+        self.setResizeAnchor(QGraphicsView.AnchorUnderMouse)
+        self.setDragMode(QGraphicsView.ScrollHandDrag)
+        self.setMinimumHeight(200)
+
+        self._scene = QGraphicsScene(self)
+        self.setScene(self._scene)
+        self._pixmap_item = QGraphicsPixmapItem()
+        self._scene.addItem(self._pixmap_item)
+
+        self._placeholder = QGraphicsTextItem("No image")
+        self._placeholder.setDefaultTextColor(QColor("#888"))
+        self._scene.addItem(self._placeholder)
+
+        self._has_image = False
+        self._auto_fit = True
+
+    def set_image(self, path: str | Path | None) -> None:
+        if path is None:
+            self._set_placeholder("No image")
+            return
+        path = Path(path)
+        if not path.exists():
+            self._set_placeholder(f"Missing: {path}")
+            return
+        pixmap = QPixmap(str(path))
+        if pixmap.isNull():
+            self._set_placeholder("Failed to load image")
+            return
+        self._has_image = True
+        self._auto_fit = True
+        self._pixmap_item.setPixmap(pixmap)
+        self._pixmap_item.setVisible(True)
+        self._placeholder.setVisible(False)
+        self._scene.setSceneRect(QRectF(pixmap.rect()))
+        self.resetTransform()
+        self.fitInView(self._pixmap_item, Qt.KeepAspectRatio)
+
+    def wheelEvent(self, event) -> None:  # noqa: N802 - Qt naming
+        if not self._has_image:
+            return
+        delta = event.angleDelta().y()
+        if delta == 0:
+            return
+        factor = 1.2 if delta > 0 else 1 / 1.2
+        self._auto_fit = False
+        self.scale(factor, factor)
+
+    def mouseDoubleClickEvent(self, event) -> None:  # noqa: N802 - Qt naming
+        if self._has_image:
+            self._auto_fit = True
+            self.resetTransform()
+            self.fitInView(self._pixmap_item, Qt.KeepAspectRatio)
+        super().mouseDoubleClickEvent(event)
+
+    def resizeEvent(self, event) -> None:  # noqa: N802 - Qt naming
+        super().resizeEvent(event)
+        if self._has_image and self._auto_fit:
+            self.fitInView(self._pixmap_item, Qt.KeepAspectRatio)
+        self._center_placeholder()
+
+    def _set_placeholder(self, text: str) -> None:
+        self._has_image = False
+        self._auto_fit = True
+        self._pixmap_item.setPixmap(QPixmap())
+        self._pixmap_item.setVisible(False)
+        self._placeholder.setPlainText(text)
+        self._placeholder.setVisible(True)
+        self._scene.setSceneRect(QRectF(0, 0, self.viewport().width(), self.viewport().height()))
+        self._center_placeholder()
+
+    def _center_placeholder(self) -> None:
+        if not self._placeholder.isVisible():
+            return
+        view_rect = self.viewport().rect()
+        center_scene = self.mapToScene(view_rect.center())
+        br = self._placeholder.boundingRect()
+        self._placeholder.setPos(
+            QPointF(center_scene.x() - br.width() / 2, center_scene.y() - br.height() / 2)
+        )

canns/pipeline/asa_gui/views/widgets/log_box.py

@@ -0,0 +1,16 @@
+"""Log output widget."""
+
+from __future__ import annotations
+
+from PySide6.QtWidgets import QTextEdit
+
+
+class LogBox(QTextEdit):
+    def __init__(self, parent=None) -> None:
+        super().__init__(parent)
+        self.setReadOnly(True)
+        self.setMinimumHeight(160)
+        self.setPlaceholderText("Logs will appear here.")
+
+    def log(self, msg: str) -> None:
+        self.append(msg)

canns/pipeline/asa_gui/views/widgets/pathcompare_tab.py

@@ -0,0 +1,200 @@
+"""PathCompare result tab (PNG + optional GIF)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtCore import Qt, QTimer, QUrl
+from PySide6.QtGui import QDesktopServices, QMovie
+from PySide6.QtWidgets import (
+    QHBoxLayout,
+    QLabel,
+    QProgressBar,
+    QPushButton,
+    QSplitter,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .image_viewer import ImageViewer
+
+
+class _FitGifLabel(QLabel):
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._movie: QMovie | None = None
+        self.setAlignment(Qt.AlignCenter)
+
+    def setMovie(self, movie: QMovie) -> None:  # type: ignore[override]
+        self._movie = movie
+        super().setMovie(movie)
+        movie.frameChanged.connect(self._on_frame)
+        self._on_frame()
+
+    def clearMovie(self) -> None:
+        if self._movie is None:
+            return
+        try:
+            self._movie.frameChanged.disconnect(self._on_frame)
+        except Exception:
+            pass
+        self._movie = None
+        self.clear()
+
+    def resizeEvent(self, event) -> None:  # noqa: N802 - Qt naming
+        super().resizeEvent(event)
+        self._on_frame()
+
+    def _on_frame(self, *_):
+        if self._movie is None:
+            return
+        pix = self._movie.currentPixmap()
+        if pix.isNull():
+            return
+        scaled = pix.scaled(self.size(), Qt.KeepAspectRatio, Qt.SmoothTransformation)
+        self.setPixmap(scaled)
+
+
+class PathCompareTab(QWidget):
+    def __init__(self, title: str = "Path Compare") -> None:
+        super().__init__()
+        self.title = title
+        self._gif_movie: QMovie | None = None
+        self._gif_retry_count = 0
+        self._gif_last_path: Path | None = None
+
+        root = QVBoxLayout(self)
+        self.header = QLabel(title)
+        self.header.setStyleSheet("font-weight: 600;")
+        root.addWidget(self.header)
+
+        actions = QHBoxLayout()
+        self.btn_open_anim = QPushButton("Open Animation")
+        self.btn_open_anim.setEnabled(False)
+        self.btn_open_anim.clicked.connect(self._open_animation)
+        actions.addWidget(self.btn_open_anim)
+        actions.addStretch(1)
+        root.addLayout(actions)
+
+        self.splitter = QSplitter(Qt.Vertical)
+
+        png_wrap = QWidget()
+        png_layout = QVBoxLayout(png_wrap)
+        png_layout.setContentsMargins(0, 0, 0, 0)
+        self.png_label = QLabel("PNG")
+        self.png_label.setStyleSheet("color: #666;")
+        png_layout.addWidget(self.png_label)
+        self.png_view = ImageViewer()
+        png_layout.addWidget(self.png_view, 1)
+
+        gif_wrap = QWidget()
+        gif_layout = QVBoxLayout(gif_wrap)
+        gif_layout.setContentsMargins(0, 0, 0, 0)
+        self.gif_label = QLabel("Animation")
+        self.gif_label.setStyleSheet("color: #666;")
+        gif_layout.addWidget(self.gif_label)
+        self.gif_view = _FitGifLabel("No animation yet")
+        self.gif_view.setMinimumHeight(220)
+        self.gif_view.setStyleSheet("border: 1px solid #ddd; background: #fafafa;")
+        gif_layout.addWidget(self.gif_view, 1)
+
+        self.anim_progress = QProgressBar()
+        self.anim_progress.setRange(0, 100)
+        self.anim_progress.setValue(0)
+        self.anim_progress.setVisible(False)
+        gif_layout.addWidget(self.anim_progress)
+
+        self.splitter.addWidget(png_wrap)
+        self.splitter.addWidget(gif_wrap)
+        self.splitter.setStretchFactor(0, 1)
+        self.splitter.setStretchFactor(1, 1)
+        root.addWidget(self.splitter, 1)
+
+        self.set_artifacts(None, None)
+
+    def set_artifacts(self, png_path: Path | None, gif_path: Path | None) -> None:
+        self._animation_path = None
+        title = self.title
+        if png_path:
+            title = f"{self.title} — {png_path.name}"
+        elif gif_path:
+            title = f"{self.title} — {gif_path.name}"
+        self.header.setText(title)
+
+        if png_path and png_path.exists():
+            self.png_label.setText(f"PNG: {png_path.name}")
+            self.png_view.set_image(png_path)
+        else:
+            self.png_label.setText("PNG: (none)")
+            self.png_view.set_image(None)
+
+        if self._gif_movie is not None:
+            try:
+                self.gif_view.clearMovie()
+            except Exception:
+                pass
+            self._gif_movie.stop()
+            self._gif_movie.deleteLater()
+            self._gif_movie = None
+
+        if gif_path and gif_path.exists():
+            self._gif_last_path = gif_path
+            self._gif_retry_count = 0
+            self._load_gif_movie(gif_path)
+            self._animation_path = gif_path
+        else:
+            self.gif_label.setText("Animation: (none)")
+            try:
+                self.gif_view.clearMovie()
+            except Exception:
+                self.gif_view.clear()
+            self.gif_view.setText("No animation yet")
+
+        self.btn_open_anim.setEnabled(self._animation_path is not None)
+
+    def set_animation(self, path: Path | None) -> None:
+        if self._gif_movie is not None:
+            try:
+                self.gif_view.clearMovie()
+            except Exception:
+                pass
+            self._gif_movie.stop()
+            self._gif_movie.deleteLater()
+            self._gif_movie = None
+
+        if path and path.exists():
+            self._animation_path = path
+            self.gif_label.setText(f"Animation (MP4): {path.name}")
+            self.gif_view.setText("MP4 preview not available. Use Open Animation.")
+        else:
+            self._animation_path = None
+            self.gif_label.setText("Animation: (none)")
+            self.gif_view.setText("No animation yet")
+        self.btn_open_anim.setEnabled(self._animation_path is not None)
+
+    def set_animation_progress(self, pct: int) -> None:
+        pct = max(0, min(100, int(pct)))
+        self.anim_progress.setVisible(True)
+        self.anim_progress.setValue(pct)
+        if pct >= 100:
+            self.anim_progress.setVisible(False)
+
+    def _open_animation(self) -> None:
+        if self._animation_path is None:
+            return
+        QDesktopServices.openUrl(QUrl.fromLocalFile(str(self._animation_path)))
+
+    def _load_gif_movie(self, gif_path: Path) -> None:
+        self.gif_label.setText(f"Animation (GIF): {gif_path.name}")
+        self._gif_movie = QMovie(str(gif_path))
+        if self._gif_movie.isValid():
+            self.gif_view.setMovie(self._gif_movie)
+            self._gif_movie.start()
+            return
+
+        self.gif_view.setText("GIF is not ready yet…")
+        self._gif_retry_count += 1
+        if self._gif_retry_count <= 10:
+            QTimer.singleShot(200, lambda: self._load_gif_movie(gif_path))
+        else:
+            self.gif_view.setText("GIF loaded but QMovie is invalid")