prepare v0.4.0 release

Author: shrimbly

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to the Sharp Frames project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-07-16
+
+### Added
+- Scrollable frame timeline with keyboard navigation and full-result visualization
+- Resolution-normalized focus scoring for more consistent comparisons across source sizes
+- Cross-platform CI coverage for Python 3.10 through 3.13 on Linux, macOS, and Windows
+- Regression coverage for selection quality, output collisions, cancellation, and runtime cleanup
+
+### Changed
+- Selection methods now balance sharpness and temporal distribution more consistently
+- Frame extraction, analysis, preview, and saving pipelines provide stricter validation and failure reporting
+- Image-directory exports preserve content while correctly handling format conversion and case-insensitive filename collisions
+- Configuration and selection screens provide clearer controls, status, and keyboard behavior
+
+### Fixed
+- FFmpeg and FFprobe process cleanup, cancellation, timeout, and pipe handling
+- Partial or failed image reads being treated as valid zero-quality frames
+- Selection previews disagreeing with the frames produced during processing
+- Output metadata reporting frames that were not successfully saved
+- Platform-specific dependency guidance and Windows-safe process startup
+
 ## [0.3.1] - 2025-01-29
 
 ### Fixed
@@ -136,4 +157,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - outlier-removal: Remove outliers based on comparison with neighbors
 - Interactive mode with guided prompts
 - Proper Python package structure for pip and pipx installation
-- Command-line interface with `sharp-frames` command 
+- Command-line interface with `sharp-frames` command

README.md

@@ -136,8 +136,11 @@ sharp-frames photos selected --selection-method outlier-removal --outlier-sensit
 
 1. **Validation**: Checks input paths, file formats, and system dependencies
 2.  **Extraction**: Videos are extracted to frames at specified FPS using FFmpeg
-3.  **Analysis**: Calculates sharpness scores using Laplacian variance in parallel
-4.  **Selection**: Applies chosen algorithm to select the best frames/images
+3.  **Analysis**: Normalizes analysis resolution, lightly denoises each image,
+    and combines Laplacian variance with Tenengrad focus scoring in parallel.
+    Unreadable inputs are excluded and reported.
+4.  **Selection**: Applies the chosen source-aware algorithm to select the best
+    naturally ordered frames/images.
 5.  **Output**: Saves selected content with metadata including scores and parameters
 
 ## Output

RELEASE_NOTES.md

@@ -1,53 +1,30 @@
-# Sharp Frames v0.2.0 Release Notes
+# Sharp Frames v0.4.0 Release Notes
 
-## New Features
+## Highlights
 
-### Textual Interface (Default)
-- Replaces command-line prompts with step-by-step wizard
-- Real-time input validation and error feedback
-- Enhanced error messages with specific guidance
+- Explore the complete analyzed frame set in a scrollable timeline with keyboard navigation.
+- Get more reliable selections from resolution-normalized focus scoring and improved temporal distribution.
+- Preview and execution now share the same selection rules, so displayed counts and chosen frames agree.
 
-### Video Directory Processing
-- Process all videos in a folder with a single command
-- Automatically detects and processes supported video formats
-- Maintains individual processing settings for each video
+## Reliability and Compatibility
 
-### Usage Changes
-```bash
-# New default behavior
-sharp-frames                    # Launches textual interface
-
-# Existing functionality unchanged  
-sharp-frames input.mp4 output/  # Direct processing
-sharp-frames video_folder/ output/  # Process all videos in folder
-sharp-frames --interactive      # Legacy prompts
-```
-
-## Technical Changes
+- Hardened FFmpeg and FFprobe cancellation, timeouts, output draining, and temporary-directory cleanup.
+- Unreadable images are excluded and reported instead of silently receiving valid-looking scores.
+- Image exports handle format conversion, partial failures, metadata accuracy, and case-insensitive filename collisions.
+- CI covers Linux, macOS, and Windows on Python 3.10, 3.11, 3.12, and 3.13.
 
-### Added
-- Path validation with existence/permission checking
-- Numeric field validation with range checking
-- Thread-safe subprocess management
-- UI component testing
-- Enhanced error analysis and reporting
+## Interface Improvements
 
-### Fixed
-- Configuration parameter mapping
-- Resource cleanup (temp files, subprocesses)
-- Error message specificity
+- Clearer configuration controls and validation feedback.
+- Improved selection chart contrast, spacing, scrolling, and keyboard controls.
+- More actionable dependency and processing errors across supported platforms.
 
-## Breaking Changes
-- `sharp-frames` without arguments now launches UI instead of showing help
-- Use `sharp-frames --help` for command-line help
+## Upgrade
 
-## Installation
 ```bash
 pip install --upgrade sharp-frames
 # or
 pipx upgrade sharp-frames
 ```
 
-## Dependencies
-- Added: `textual>=0.41.0`
-- All existing dependencies unchanged 
+FFmpeg and FFprobe remain required for video processing and must be available on `PATH`.

docs/APPLICATION_AUDIT.md

@@ -205,6 +205,22 @@ and CI across supported Python and operating-system versions.
 The following quality improvements are important but are deferred until the
 Critical and High correctness and safety defects above are closed.
 
+### Implementation status (2026-07-15)
+
+| Finding | Current status |
+| --- | --- |
+| Q1 | Baseline implemented. Modern and direct-CLI analysis now normalize the long edge to 512 pixels before scoring. The synthetic cross-resolution ratio fell from 4.0 to approximately 1.39, guarded by a `< 1.5` regression threshold. A fine-detail probe improved sharp/mild-blur separation from approximately 1.17× at 256 pixels to 1.56× at 512 pixels. |
+| Q2 | Baseline implemented. A 5×5 Gaussian denoise pass now feeds an equal-weight, log-normalized Laplacian/Tenengrad score. In the deterministic noise probe, the clean edge scores about 4× above the noisy blurred image. Real labeled-corpus validation remains under Q6. |
+| Q3 | Natural, case-insensitive numbered ordering is implemented for image directories, video directories, extracted frame discovery, and the direct CLI. Optional EXIF chronology remains a future enhancement. |
+| Q4 | Local outlier comparison now uses the neighbor median and median absolute deviation with a stable zero-MAD fallback. A single extreme high score no longer masks a real blurry frame. Scene-aware windows remain future work. |
+| Q5 | Resolved for the modern pipeline. Failed reads are excluded instead of receiving score zero; all-failed inputs stop safely; structured counts and paths are added to metadata; and the Textual selection screen reports exclusions. |
+| Q6 | In progress. Deterministic probes now track resolution invariance, noise resistance, chronology, unreadable exclusion, and synthetic outlier precision/recall. A representative real-media corpus, duplicate metric, and cross-camera baseline remain outstanding. |
+| Q7 | In progress. The chart now scrolls horizontally across the full timeline with guaranteed bar separation. Source-boundary markers and per-frame selection explanations remain outstanding. |
+
+The focus-score metadata records
+`normalized_laplacian_tenengrad_v1` and the 512-pixel analysis scale so future
+quality comparisons can distinguish algorithm versions.
+
 ### Q1. Normalize analysis resolution
 
 Laplacian variance is strongly resolution-dependent. The same synthetic edge

sharp_frames/__init__.py

@@ -1,6 +1,6 @@
 """Sharp Frames - Extract, score, and select the best frames from a video, video directory, or image directory."""
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 
 import subprocess
 import sys

sharp_frames/focus_scoring.py

@@ -0,0 +1,46 @@
+"""Resolution-normalized, noise-resistant focus scoring."""
+
+import cv2
+import numpy as np
+
+
+ANALYSIS_LONG_EDGE = 512
+FOCUS_SCORE_METHOD = "normalized_laplacian_tenengrad_v1"
+DENOISE_KERNEL = (5, 5)
+DENOISE_SIGMA = 1.0
+LAPLACIAN_WEIGHT = 0.5
+TENENGRAD_WEIGHT = 0.5
+
+
+def normalize_analysis_image(image: np.ndarray) -> np.ndarray:
+    """Return a grayscale image at the canonical analysis resolution."""
+    if image is None or image.size == 0:
+        raise ValueError("Focus analysis requires a non-empty image")
+    if image.ndim == 3:
+        image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+
+    height, width = image.shape
+    scale = ANALYSIS_LONG_EDGE / max(height, width)
+    target_size = (
+        max(1, round(width * scale)),
+        max(1, round(height * scale)),
+    )
+    interpolation = cv2.INTER_AREA if scale < 1 else cv2.INTER_CUBIC
+    return cv2.resize(image, target_size, interpolation=interpolation)
+
+
+def calculate_focus_score(image: np.ndarray) -> float:
+    """Combine Laplacian variance and Tenengrad after light denoising."""
+    normalized = normalize_analysis_image(image)
+    denoised = cv2.GaussianBlur(normalized, DENOISE_KERNEL, DENOISE_SIGMA)
+
+    laplacian_variance = cv2.Laplacian(denoised, cv2.CV_64F).var()
+    gradient_x = cv2.Sobel(denoised, cv2.CV_64F, 1, 0, ksize=3)
+    gradient_y = cv2.Sobel(denoised, cv2.CV_64F, 0, 1, ksize=3)
+    tenengrad = np.mean((gradient_x * gradient_x) + (gradient_y * gradient_y))
+
+    combined_log_score = (
+        np.log1p(laplacian_variance) * LAPLACIAN_WEIGHT
+        + np.log1p(tenengrad) * TENENGRAD_WEIGHT
+    )
+    return float(np.expm1(combined_log_score))

sharp_frames/processing/frame_extractor.py

@@ -18,6 +18,7 @@
     SUPPORTED_IMAGE_EXTENSIONS,
     get_ffmpeg_installation_hint,
     get_video_files_in_directory,
+    natural_path_key,
 )
 
 if TYPE_CHECKING:
@@ -308,8 +309,7 @@ def _filter_image_files(self, directory: str) -> List[str]:
         except OSError as e:
             raise FileNotFoundError(f"Could not scan directory {directory}: {e}")
 
-        # Sort for consistent ordering
-        image_files.sort()
+        image_files.sort(key=natural_path_key)
         return image_files
 
     def _get_image_output_name(self, image_path: str) -> str:
@@ -622,8 +622,7 @@ def _get_extracted_frame_files(self, temp_dir: str) -> List[str]:
         except OSError:
             return []
 
-        # Sort by filename to maintain frame order
-        frame_files.sort()
+        frame_files.sort(key=natural_path_key)
         return frame_files
 
     def _get_supported_image_extensions(self) -> set:

sharp_frames/processing/frame_saver.py

@@ -22,6 +22,8 @@ class ImageProcessingError(Exception):
 
 class FrameSaver:
     """Handles saving selected frames to disk with proper naming conventions."""
+
+    METADATA_FILENAME = "selected_metadata.json"
 
     def __init__(self, show_progress: bool = True):
         """Initialize FrameSaver.
@@ -79,13 +81,16 @@ def save_frames(self, selected_frames: List[FrameData], config: Dict[str, Any])
             print(f"Error creating output directory: {e}")
             return False
 
-        # Check for overwrite if needed
-        if not force_overwrite and not self._check_output_directory_overwrite(output_dir):
-            return False
-
         output_filenames = self._plan_output_filenames(
             selected_frames, input_type, output_format
         )
+
+        # Check only paths this run intends to create. Unrelated files (for
+        # example Finder's .DS_Store) are not overwrite risks.
+        if not force_overwrite and not self._check_output_directory_overwrite(
+            output_dir, output_filenames
+        ):
+            return False
 
         success_count = 0
         metadata_list = []
@@ -294,7 +299,7 @@ def _save_metadata(
             config: Configuration dictionary
             selected_frames: List of selected frames
         """
-        metadata_path = os.path.join(output_dir, "selected_metadata.json")
+        metadata_path = os.path.join(output_dir, self.METADATA_FILENAME)
 
         try:
             # Create comprehensive metadata
@@ -388,33 +393,45 @@ def _get_current_timestamp(self) -> str:
         import datetime
         return datetime.datetime.now().isoformat()
 
-    def _check_output_directory_overwrite(self, output_dir: str) -> bool:
-        """Return whether saving may proceed without unapproved overwrites."""
+    def _check_output_directory_overwrite(
+        self, output_dir: str, output_filenames: List[str]
+    ) -> bool:
+        """Return whether planned outputs can be written without overwriting."""
         if not os.path.exists(output_dir):
             return True
 
         try:
-            existing_files = [f for f in os.listdir(output_dir) 
-                            if os.path.isfile(os.path.join(output_dir, f))]
+            planned_names = {
+                filename.casefold()
+                for filename in [*output_filenames, self.METADATA_FILENAME]
+            }
+            conflicting_entries = [
+                name
+                for name in os.listdir(output_dir)
+                if name.casefold() in planned_names
+            ]
 
-            if existing_files:
+            if conflicting_entries:
                 # In non-interactive mode (TUI/thread context), just warn without prompting
                 if not self.show_progress:  # show_progress=False indicates non-interactive context
                     conflicting_paths = [
                         os.path.join(output_dir, filename)
-                        for filename in sorted(existing_files)
+                        for filename in sorted(conflicting_entries)
                     ]
                     print(
-                        f"Error: Output directory '{output_dir}' contains "
-                        f"{len(existing_files)} file(s). No files were written. "
-                        "Choose an empty directory or enable force overwrite."
+                        f"Error: {len(conflicting_entries)} planned output path(s) "
+                        f"already exist in '{output_dir}'. No files were written. "
+                        "Choose another directory or enable force overwrite."
                     )
                     print("Conflicting files: " + ", ".join(conflicting_paths))
                     return False
 
                 # Interactive mode - prompt user
-                print(f"Warning: Output directory '{output_dir}' contains {len(existing_files)} files.")
-                print("Existing files may be overwritten.")
+                print(
+                    f"Warning: {len(conflicting_entries)} planned output path(s) "
+                    f"already exist in '{output_dir}'."
+                )
+                print("Those existing outputs may be overwritten.")
 
                 while True:
                     response = input("Continue anyway? (y/n): ").strip().lower()