seavision-python 0.1.1__py3-none-any.whl

seavision/gui/validation/video_cache.py

@@ -0,0 +1,215 @@
+"""
+Local file cache for remote-sourced videos (e.g. from S3)
+
+Downloads videos from the remote source to a local cache directory so that
+SeekableVideoSource can open them with random access seeking. The cache
+persists between sessions.
+
+Supported sources:
+- S3 (e.g. s3://my-bucket/path/to/video.mp4)
+
+This module currently depends on boto3 but has no Qt dependency.
+"""
+
+import hashlib
+import logging
+import shutil
+from pathlib import Path
+
+from seavision.engine.source.s3 import parse_s3_uri
+
+logger = logging.getLogger(__name__)
+
+try:
+    import boto3
+    from botocore.exceptions import ClientError, NoCredentialsError
+    BOTO3_AVAILABLE = True
+except ImportError:
+    BOTO3_AVAILABLE = False
+
+
+_DEFAULT_CACHE_DIR = Path.home() / ".seavision" / "cache"
+
+
+class S3VideoCache:
+    """
+    Local file cache for S3 videos.
+
+    Downloads videos from S3 on demand and stored them in a flat directory keyed
+    by a hash of the S3 URI.
+    """
+
+    def __init__(self, cache_dir: Path | None = None):
+        self.cache_dir = cache_dir or _DEFAULT_CACHE_DIR
+
+    def _ensure_cache_dir(self):
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    @staticmethod
+    def _cache_key(s3_uri: str) -> str:
+        """
+        Derive a filesystem-safe cache ky from an S3 URI.
+
+        Uses SHA-256 truncated to 16 hex chars plus the original filename for
+        readability.
+        """
+        uri_hash = hashlib.sha256(s3_uri.encode()).hexdigest()[:16]
+        filename = Path(s3_uri.split("/")[-1]).name
+        return f"{uri_hash}_{filename}"
+    
+    def get_cached_path(self, s3_uri: str) -> str | None:
+        """
+        Return the local cached path for an S3 URI if it exists.
+
+        Does not attempt to download. Returns None if the file is not in the
+        cache.
+        """ 
+        cache_key = self._cache_key(s3_uri)
+        cache_path = self.cache_dir / cache_key
+        if cache_path.exists():
+            return str(cache_path)
+        return None
+
+    def get_or_download(
+        self,
+        s3_uri: str,
+        profile_name: str | None = None
+    ) -> Path:
+        """
+        Return the local path for an S3 video, downloading if needed.
+
+        Downloads to a .downloading temp file first, then renames automatically
+        to prevent partial files being treated as complete.
+        """
+        if not BOTO3_AVAILABLE:
+            raise ImportError(
+                "boto3 is required for S3 video downloads. "
+                "Install with pip install boto3"
+            )
+        
+        self._ensure_cache_dir()
+        cached = self.get_cached_path(s3_uri)
+
+        if cached is not None:
+            logger.debug("Cache hit for %s", s3_uri)
+            return Path(cached)
+        
+        # Not cached - need to download
+        local_path = self.cache_dir / self._cache_key(s3_uri)
+        
+        logger.info("Downloading %s to cache...", s3_uri)
+        bucket, key = parse_s3_uri(s3_uri)
+        tmp_path = local_path.with_suffix(".downloading")
+
+        try:
+            session = boto3.Session(profile_name=profile_name)
+            s3_client = session.client("s3")
+
+            s3_client.download_file(bucket, key, str(tmp_path))
+            tmp_path.rename(local_path)
+            logger.info("Cached %s to %s", s3_uri, local_path)
+            return local_path
+        
+        except NoCredentialsError:
+            if tmp_path.exists():
+                tmp_path.unlink()
+            raise RuntimeError(
+                "AWS credentials not found. "
+                "Run 'aws sso login' before opening S3 sessions."
+            )
+        
+        except ClientError as e:
+            if tmp_path.exists():
+                tmp_path.unlink()
+            error_code = e.response.get("Error", {}).get("Code", "")
+            if error_code == "ExpiredToken":
+                raise RuntimeError(
+                    "AWS credentials have expired. "
+                    "Run 'aws sso login' to refresh them."
+                )
+            raise RuntimeError(
+                f"Failed to download {s3_uri}:\n\n{e}"
+            ) from e
+        
+        except Exception as e:
+            if tmp_path.exists():
+                tmp_path.unlink()
+            raise RuntimeError(
+                f"Failed to download {s3_uri}:\n\n{e}"
+            ) from e
+        
+    
+    def calculate_download_size(
+        self,
+        s3_uris: list[str],
+        profile_name: str | None = None,
+    ) -> tuple[int, list[str]]:
+        """
+        Calculate total download size for uncached S3 URIs using HEAD requests.
+
+        Returns:
+            Tuple of (total_bytes, uris_needing_downloading)
+        """
+        if not BOTO3_AVAILABLE:
+            raise ImportError(
+                "boto3 is required for S3 video downloads. "
+                "Install with pip install boto3"
+            )
+        
+        session = boto3.Session(profile_name=profile_name)
+        s3_client = session.client("s3")
+
+        total_bytes = 0
+        need_download: list[str] = []
+
+        for uri in s3_uris:
+            if (self.cache_dir / self._cache_key(uri)).exists():
+                continue
+
+            bucket, key = parse_s3_uri(uri)
+            try:
+                response = s3_client.head_object(
+                    Bucket=bucket,
+                    Key=key
+                )
+                total_bytes += response["ContentLength"]
+                need_download.append(uri)
+            
+            except (ClientError, NoCredentialsError) as e:
+                raise RuntimeError(
+                    f"Cannot determine size of {uri}: {e}"
+                ) from e
+
+            except Exception as e:
+                # Catches connection errors, DNS failures, timeouts,
+                # and any other network-level issue from boto3/urllib3
+                raise RuntimeError(
+                    f"Cannot connect to S3 for {uri}:\n\n{e}"
+                ) from e
+            
+        return total_bytes, need_download
+    
+
+    def cache_size(self) -> int:
+        """Return total size of cached files in bytes."""
+        if not self.cache_dir.exists():
+            return 0
+        return sum(
+            f.stat().st_size
+            for f in self.cache_dir.iterdir()
+            if f.is_file() and not f.name.endswith(".downloading")
+        )
+    
+    def clear_cache(self) -> int:
+        """Delete all cached files. Returns bytes freed."""
+        freed = self.cache_size()
+        if self.cache_dir.exists():
+            shutil.rmtree(self.cache_dir)
+            logger.info(
+                "Cleared cache: %.1f MB freed", freed / (1024**2)
+            )
+        return freed
+    
+    def is_cached(self, s3_uri: str) -> bool:
+        """Check whether a specific URI is already cached."""
+        return (self.cache_dir / self._cache_key(s3_uri)).exists()

seavision/gui/validation/video_list.py

@@ -0,0 +1,140 @@
+"""
+Video list sidebar widget.
+
+Shows all videos in the current session with detection counts and review
+progress. Clicking a video switched the viewer and detection table to that
+video.
+"""
+
+from pathlib import Path
+
+from PySide6.QtCore import Signal, Qt
+from PySide6.QtGui import QBrush, QColor
+from PySide6.QtWidgets import (
+    QLabel,
+    QListWidget,
+    QListWidgetItem,
+    QVBoxLayout,
+    QWidget,
+)
+
+_COLOUR_NOT_STARTED = QColor(150, 150, 150) # GREY
+_COLOUR_IN_PROGRESS = QColor("#CC7A00")  # AMBER/ORANGE
+_COLOUR_COMPLETE = QColor(60, 160, 60)      # GREEN
+_COLOUR_UNAVAILABLE = QColor(180, 180, 180)  # LIGHT GREY for videos that can't be loaded (e.g. missing S3 creds)
+
+
+class VideoListWidget(QWidget):
+    """
+    Sidebar showing all videos in the current session.
+
+    Signals:
+        video_selected: Emitted when the users clicks a video. Carries the
+            source_file string.
+    """
+
+    video_selected = Signal(str)
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+
+        # --- Main layout ---
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 4, 0, 0)
+
+        # --- Header ---
+        self._header = QLabel("Videos:")
+        self._header.setStyleSheet("font-weight: bold; padding: 4px;")
+        layout.addWidget(self._header)
+
+        # --- Video list ---
+        self._list = QListWidget()
+        self._list.setAlternatingRowColors(True)
+        self._list.currentItemChanged.connect(self._on_item_changed)
+        layout.addWidget(self._list)
+
+    def set_videos(self, video_info: list[dict]) -> None:
+        """
+        Populate the list with video entries.
+
+        Args:
+            video_info: List of dicts with keys:
+                source_file, total, rviewed, available.
+        """
+        self._list.blockSignals(True)
+        self._list.clear()
+
+        for info in video_info:
+            source_file = info["source_file"]
+            filename = Path(source_file).name
+            total = info["total"]
+            reviewed = info["reviewed"]
+            available = info.get("available", True)
+
+            text = f"{filename} ({reviewed}/{total})"
+            item = QListWidgetItem(text)
+            item.setToolTip(source_file)
+            item.setData(Qt.ItemDataRole.UserRole, source_file)
+
+            if not available:
+                item.setForeground(QBrush(_COLOUR_UNAVAILABLE))
+                item.setFlags(
+                    item.flags() & ~Qt.ItemFlag.ItemIsEnabled
+                )
+                item.setToolTip(f"{source_file} (not found)")
+            elif reviewed == 0:
+                item.setForeground(QBrush(_COLOUR_NOT_STARTED))
+            elif reviewed >= total:
+                item.setForeground(QBrush(_COLOUR_COMPLETE))
+            else:
+                item.setForeground(QBrush(_COLOUR_IN_PROGRESS))
+
+            self._list.addItem(item)
+
+        self._list.blockSignals(False)
+        self._header.setText(f"Videos ({len(video_info)}):")
+
+    def update_progress(
+        self, source_file: str, progress: dict
+    ) -> None:
+        """Update the progress display for a single video."""
+        for row in range(self._list.count()):
+            item = self._list.item(row)
+            if item.data(Qt.ItemDataRole.UserRole) != source_file:
+                continue
+
+            total = progress["total"]
+            reviewed = progress["reviewed"]
+            filename = Path(source_file).name
+            item.setText(f"{filename} ({reviewed}/{total})")
+
+            if reviewed == 0:
+                item.setForeground(QBrush(_COLOUR_NOT_STARTED))
+            elif reviewed >= total:
+                item.setForeground(QBrush(_COLOUR_COMPLETE))
+            else:
+                item.setForeground(QBrush(_COLOUR_IN_PROGRESS))
+            break
+
+    def _on_item_changed(
+            self, 
+            current: QListWidgetItem, 
+            _previous: QListWidgetItem,
+        ) -> None:
+        if current is None:
+            return
+        source_file = current.data(Qt.ItemDataRole.UserRole)
+        if source_file:
+            self.video_selected.emit(source_file)
+
+    def select_video(self, source_file: str) -> None:
+        """Programmatically select a video in the list."""
+        for row in range(self._list.count()):
+            item = self._list.item(row)
+            if item.data(Qt.ItemDataRole.UserRole) == source_file:
+                self._list.setCurrentItem(item)
+                return
+
+    def clear(self) -> None:
+        self._list.clear()
+        self._header.setText("Videos:")

seavision/gui/validation/video_viewer.py

@@ -0,0 +1,150 @@
+"""Video frame display widget."""
+
+from PySide6.QtCore import Signal, Qt, QPoint
+from PySide6.QtGui import QCursor, QImage, QPixmap
+from PySide6.QtWidgets import QLabel, QSizePolicy
+
+class FrameDisplay(QLabel):
+    """
+    Displays video frames sclaed to fit the available space.
+
+    Recieves QImage objects (from the video worker), converts them to QPixmap,
+    and renders them centered with correct aspect ratio. Handles window resizing
+    by re-scaling the last displayed frame.
+    """
+
+    # Emitted when the user clicks the frame in 'add' mode.
+    frame_clicked = Signal(float, float)  # x, y in frame's pixel space
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+
+        # Detection adding
+        self._add_mode = False
+        self._frame_width: int = 0
+        self._frame_height: int = 0
+
+        # Set alignment policies
+        self.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.setSizePolicy(
+            QSizePolicy.Policy.Expanding, 
+            QSizePolicy.Policy.Expanding
+        )
+        self.setMinimumSize(320, 240)
+
+        # Placeholder appearance
+        self.setStyleSheet("background-color: #1e1e1e; color: #888888;")
+        self.setText(
+            "Open a video or session to begin\n\n"
+            "File → New Session (Ctrl+N)\n"
+            "File → Open Video (Ctrl+O)\n\n"
+            "Or drag a CSV, video or .seavision-session file here"
+        )
+
+        # Placeholder for the unscaled original frame
+        self._original_pixmap: QPixmap | None = None
+
+    def update_frame(self, image: QImage, frame_number: int,
+                     timestamp: float) -> None:
+        """
+        Display a new frame from the video worker.
+
+        Args:
+            image: The frame as a QImage.
+            frame_number: Frame index (not used here, but part of the signal
+                signature - other slots use it).
+            timestamp: Time in seconds (same)
+        """
+        # Store frame dimensions
+        self._frame_width = image.width()
+        self._frame_height = image.height()
+        
+        self._original_pixmap = QPixmap.fromImage(image)
+        self._scale_and_display()
+        
+    def _scale_and_display(self) -> None:
+        """Scale the stored pixmap to fit the current widget size."""
+        if self._original_pixmap is None:
+            return
+        
+        scaled = self._original_pixmap.scaled(
+            self.size(),
+            Qt.AspectRatioMode.KeepAspectRatio,
+            Qt.TransformationMode.SmoothTransformation
+        )
+        self.setPixmap(scaled)
+
+    
+    # --- Handle adding detection ---
+    def _widget_to_frame_coords(
+        self, widget_x: int, widget_y: int
+    ) -> tuple[float, float] | None:
+        """
+        Convert widget pixel coordinates to original frame coordinates.
+
+        The label displays the frame scaled to fit with aspect ratio preserved.
+        This method reverses that transformation.
+
+        Returns:
+            (frame_x, frame_y) in the original frame's pixel space, or None if
+            the click is outside the displayed frame area (i.e. on the
+            letterbox area).
+        """
+        pixmap = self.pixmap()
+        if pixmap is None or pixmap.isNull():
+            return None
+        
+        if self._frame_width == 0 or self._frame_height == 0:
+            return None
+        
+        # The displayed pixmap size (after scaling to fit the label)
+        display_w = pixmap.width()
+        display_h = pixmap.height()
+
+        # Calculate the label ofest
+        offset_x = (self.width() - display_w) / 2
+        offset_y = (self.height() - display_h) / 2
+
+        # Position relative to the displayed image
+        rel_x = widget_x - offset_x
+        rel_y = widget_y - offset_y
+
+        # Check bounds to see if click is in letterbox area
+        if rel_x < 0 or rel_y < 0:
+            return None
+        if rel_x > display_w or rel_y > display_h:
+            return None
+        
+        # Scale back to original frame coordinates
+        frame_x = rel_x * (self._frame_width / display_w)
+        frame_y = rel_y * (self._frame_height / display_h)
+
+        return frame_x, frame_y
+    
+    def set_add_mode(self, enabled: bool) -> None:
+        """Toggle add-detection mode. Changes the cursor as a visual cue."""
+        self._add_mode = enabled
+        if enabled:
+            self.setCursor(Qt.CursorShape.CrossCursor)
+        else:
+            self.setCursor(Qt.CursorShape.ArrowCursor)
+
+    def mousePressEvent(self, event) -> None:
+        """Handle clicks - in add mode, emit the frame coordinates."""
+        if self._add_mode and event.button() == Qt.MouseButton.LeftButton:
+            coords = self._widget_to_frame_coords(
+                event.position().x(), event.position().y()
+            )
+            if coords is not None:
+                frame_x, frame_y = coords
+                self.frame_clicked.emit(frame_x, frame_y)
+            # Exit add mode after one click
+            self.set_add_mode(False)
+        else:
+            super().mousePressEvent(event)
+
+    def resizeEvent(self, event) -> None:
+        """Re-scale the frame when the widget is resized."""
+        self._scale_and_display()
+        super().resizeEvent(event)
+