From c32a4bcb32b63c1405889bf55158263698774667 Mon Sep 17 00:00:00 2001 From: Ethanfel Date: Tue, 20 Jan 2026 00:34:47 +0100 Subject: [PATCH] Update README.md --- README.md | 140 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 124 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index ef0278f..8798f57 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,28 @@ -# 🔪 ComfyUI Sharp Frame Selector +# ComfyUI Sharpness Helper Nodes -A collection of high-performance custom nodes for **ComfyUI** designed to detect blur, calculate sharpness scores, and automatically extract the best frames from videos or image batches. +A high-performance custom node suite for **ComfyUI** designed to detect blur, calculate sharpness scores (Laplacian Variance), and efficiently extract or filter the best frames from videos and image batches. -This pack includes two distinct approaches: -1. **Parallel Video Loader:** A multi-threaded, path-based loader for processing massive video files directly from disk (Low RAM usage). -2. **Standard Sharpness Duo:** A classic filter setup for processing images/latents *inside* your existing workflow. +This pack solves two major problems in AI video workflows: +1. **Dataset Creation:** Extracting only the sharpest frames from massive movie files without crashing RAM. +2. **Generation Filtering:** Automatically discarding blurry frames from AnimateDiff or img2img outputs. ---- -![Nodes Diagram](assets/nodes.png) --- ## 🚀 Key Features -### 1. New: Parallel Video Loader (Path-Based) +### 1. Parallel Video Loader (Path-Based) * **Zero-RAM Scanning:** Scans video files directly from disk without decoding every frame to memory. -* **Multi-Threaded:** Uses all CPU cores to calculate sharpness scores at high speed. -* **Batching Support:** Includes a "Page" system to process long movies in chunks (e.g., minute-by-minute) without restarting ComfyUI. -* **Smart Selection:** Automatically skips "adjacent" frames to ensure you get a diverse selection of sharp images. +* **Multi-Threaded:** Uses all CPU cores to calculate sharpness scores at high speed (1000s of frames per minute). +* **Smart Batching:** Includes an auto-incrementing "Page" system to process long movies in chunks (e.g., minute-by-minute) without restarting ComfyUI. +* **Lazy Loading:** Only decodes and loads the final "Best N" frames into ComfyUI tensors. -### 2. Standard Sharpness Duo (Tensor-Based) +### 2. Fast Absolute Saver (Metadata) +* **Multi-Threaded Saving:** Spawns parallel workers to saturate SSD write speeds (bypassing standard PIL bottlenecks). +* **No UI Lag:** Saves images in the background without trying to render Base64 previews in the browser, preventing interface freezes. +* **Metadata Embedding:** Automatically embeds the sharpness score into the PNG/WebP metadata for dataset curation. +* **Smart Naming:** Uses original video frame numbers in filenames (e.g., `frame_001450.png`) instead of arbitrary counters. + +### 3. Standard Sharpness Duo (Tensor-Based) * **Workflow Integration:** Works with any node that outputs an `IMAGE` batch (e.g., AnimateDiff, VideoHelperSuite). * **Precision Filtering:** Sorts and filters generated frames before saving or passing to a second pass (img2img). @@ -26,7 +30,111 @@ This pack includes two distinct approaches: ## 📦 Installation -1. Clone this repository into your `custom_nodes` folder: - ```bash - cd ComfyUI/custom_nodes/ - git clone https://github.com/ethanfel/ComfyUI-Sharp-Selector.git \ No newline at end of file +1. Clone this repository into your `custom_nodes` folder: + ```bash + cd ComfyUI/custom_nodes/ + git clone [https://github.com/YOUR_USERNAME/ComfyUI-Sharpness-Helper.git](https://github.com/YOUR_USERNAME/ComfyUI-Sharpness-Helper.git) + ``` +2. Install dependencies (if needed): + ```bash + pip install opencv-python numpy + ``` +3. Restart ComfyUI. + +--- + +## 🛠️ Node Documentation + +### 1. Parallel Video Loader (Sharpness) +**Category:** `BetaHelper/Video` + +This is the recommended node for **Dataset Creation** or finding good frames in **Long Movies**. It inputs a file path, scans it in parallel, and only loads the final "Best N" frames into memory. + +| Input | Description | +| :--- | :--- | +| **video_path** | Absolute path to your video file (e.g., `D:\Movies\input.mp4`). | +| **batch_index** | **Critical.** Connect a **Primitive Node** here set to `increment`. This controls which "chunk" of the video you are viewing. | +| **scan_limit** | How many frames to process per batch (e.g., `1440`). | +| **frame_scan_step** | Speed up scanning by checking every Nth frame (e.g., `5` checks frames 0, 5, 10...). | +| **manual_skip_start** | Global offset (e.g., set to `2000` to always ignore the opening credits). | + +**Outputs:** +* `images`: The batch of the sharpest frames found. +* `scores_info`: String containing frame indices and scores (Connect to Saver). +* `batch_int`: The current batch number. +* `batch_status`: Human-readable status (e.g., *"Batch 2: Skipped 2880 frames..."*). + +> **💡 Pro Tip:** To scan a movie continuously, connect a **Primitive Node** to `batch_index`, set it to **increment**, and enable "Auto Queue" in ComfyUI. + +--- + +### 2. Fast Absolute Saver (Metadata) +**Category:** `BetaHelper/IO` + +A "Pro-Grade" saver designed for speed. It bypasses relative paths and UI previews. + +| Input | Description | +| :--- | :--- | +| **output_path** | Absolute path to save folder (e.g., `D:\Datasets\Sharp_Output`). | +| **filename_prefix** | Base name for files (e.g., `matrix_movie`). | +| **max_threads** | **0 = Auto** (Uses all CPU cores). Set manually to limit CPU usage. | +| **save_format** | `png` (Fastest) or `webp` (Smaller size). | +| **filename_with_score** | If True, appends score to filename: `frame_001450_1500.png`. | +| **scores_info** | Connect this to the `scores_info` output of the Parallel Loader to enable smart naming. | + +**Performance Note:** +* **PNG:** Uses `compress_level=1` for maximum speed. +* **WebP:** Avoid `webp_method=6` unless you need max compression; it is very CPU intensive. `4` is the recommended balance. + +--- + +### 3. Sharpness Analyzer & Selector (The Duo) +**Category:** `BetaHelper/Image` + +Use these when you already have images inside your workflow (e.g., from a generation or a standard Load Video node). + +#### Node A: Sharpness Analyzer +* **Input:** `IMAGE` batch. +* **Action:** Calculates the Laplacian Variance for every image in the batch. +* **Output:** Passes the images through + a generic score list. + +#### Node B: SharpFrame Selector +* **Input:** `IMAGE` batch (from Analyzer). +* **Action:** Sorts the batch based on the scores and picks the top N frames. +* **Output:** A reduced batch containing only the sharpest images. + +--- + +## ⚖️ Which Node Should I Use? + +| Feature | **Parallel Video Loader** | **Standard Duo** | +| :--- | :--- | :--- | +| **Input Type** | File Path (`String`) | Image Tensor (`IMAGE`) | +| **Best For** | **Long Videos / Movies** | **Generations / Short Clips** | +| **Memory Usage** | Very Low (Only loads final frames) | High (Loads all frames to RAM first) | +| **Speed** | ⚡ **Ultra Fast** (Multi-core) | 🐢 Standard (Single-core) | +| **Workflow Stage** | Start of Workflow | Middle/End of Workflow | + +--- + +## 📝 Example Workflows + +### Batch Processing a Movie for Training Data +1. Add **Parallel Video Loader**. +2. Connect a **Primitive Node** to `batch_index` (Control: `increment`). +3. Set `scan_limit` to `1000` and `frame_scan_step` to `5`. +4. Connect `images` and `scores_info` to **Fast Absolute Saver**. +5. Enable **Auto Queue** in ComfyUI extra options. + * *Result: ComfyUI will loop through your movie, extracting the 4 sharpest frames from every ~1000 frame chunk automatically.* + +### Filtering AnimateDiff Output +1. AnimateDiff Generation -> **Sharpness Analyzer**. +2. Analyzer Output -> **SharpFrame Selector** (Select Best 1). +3. Selector Output -> **Face Detailer** or **Upscaler**. + * *Result: Only the clearest frame from your animation is sent to the upscaler, saving time on blurry frames.* + +--- + +## Credits +* Built using `opencv-python` for Laplacian Variance calculation. +* Parallel processing logic for efficient large-file handling. \ No newline at end of file