191 lines
7.8 KiB
Markdown
191 lines
7.8 KiB
Markdown
### **Updated Project File Structure**
|
|
|
|
```text
|
|
ComfyUI-Ultimate-Sampler-Grid/
|
|
├── __init__.py # Server Routes & Node Mappings
|
|
├── sampler_node.py # Main "Sampler Grid" Node
|
|
├── dashboard_node.py # "Dashboard Viewer" Node
|
|
├── config_builder_node.py # "Config Builder" Node
|
|
├── json_text_node.py # "Smart JSON" Node
|
|
│
|
|
├── generation_orchestrator.py # The "Conductor" (Loop Logic)
|
|
├── image_generation.py # KSampler & VAE Wrappers
|
|
├── model_loader.py # Checkpoint/LoRA Loading Logic
|
|
├── model_cache.py # 3-Tier Model Caching System
|
|
├── remote_vae.py # Remote VAE Offloading
|
|
│
|
|
├── lora_utils.py # LoRA Searching & Validation
|
|
├── trigger_words.py # CivitAI Trigger Word Fetching
|
|
├── html_generator.py # Reads /resources/ to build the Dashboard HTML
|
|
│
|
|
├── web/ # [ComfyUI Integration Layer]
|
|
│ ├── dashboard.js # Registers Dashboard Node & Message Handling
|
|
│ ├── config_builder.js # Registers Builder Node & Custom UI Widget
|
|
│ └── smart_json_text.js # Registers JSON Node & Syntax Highlighting
|
|
│
|
|
└── resources/ # [The Dashboard SPA Core]
|
|
├── template.html # HTML Skeleton for the generated report
|
|
├── report.css # Styling (Infinite Canvas, Cards, Modals)
|
|
├── logic_init.js # Bootstrapper (Load JSON, Init State)
|
|
├── logic_state.js # State Store (Redux-style: filters, favorites)
|
|
├── logic_pipeline.js # Data Processing (Filter -> Sort -> Layout)
|
|
├── logic_virtual.js # Virtual DOM / Infinite Scroller Engine
|
|
├── logic_ui.js # UI Renderer (DOM creation, Modal handling)
|
|
├── logic_events.js # Interaction Handler (Hotkeys, API calls)
|
|
└── logic_utils.js # Helpers (Debounce, Formatters)
|
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
### **Project Architecture Overview**
|
|
|
|
**ComfyUI-Ultimate-Sampler-Grid** is a hybrid application.
|
|
|
|
1. **The Backend (Python):** Runs inside ComfyUI. It orchestrates the grid generation, manages resources (caching/loading), and serves the API.
|
|
2. **The Frontend Bridge (JS):** Runs in the ComfyUI browser tab. It registers the custom nodes and widgets.
|
|
3. **The Dashboard SPA (HTML/JS/CSS):** A standalone, virtualized "IDE" for viewing results. It is generated by the backend but runs entirely in the client's browser, communicating back to the server only when saving changes.
|
|
|
|
---
|
|
|
|
### **1. The Backend: Core Logic & Orchestration**
|
|
|
|
*Located in the root directory.*
|
|
|
|
* **`sampler_node.py`** (The Interface)
|
|
* **Role:** The primary ComfyUI node. Validates inputs and passes control to the orchestrator.
|
|
* **Key Logic:** Disables caching features if "Optional" inputs are connected (since external changes can't be tracked).
|
|
|
|
|
|
* **`generation_orchestrator.py`** (The Conductor)
|
|
* **Role:** Manages the generation loop.
|
|
* **Key Logic:**
|
|
* **Smart Skip:** Checks `manifest.json` to skip existing images.
|
|
* **Lookahead:** Triggers background loading for the *next* job while the current one runs.
|
|
* **Interrupts:** Catches cancel signals to save the manifest before stopping.
|
|
|
|
|
|
|
|
|
|
* **`image_generation.py`** (The Worker)
|
|
* **Role:** Wraps KSampler and VAE Decode.
|
|
* **Key Logic:** Implements `flush_batch_with_vae` to save images and update the manifest in chunks (preventing VRAM overflow).
|
|
|
|
|
|
* **`html_generator.py`** (The Builder)
|
|
* **Role:** Compiles the SPA.
|
|
* **Key Logic:** Reads all files from `/resources/`, injects them into `template.html`, and embeds the `manifest.json` data as a JavaScript variable (`fullManifest`), allowing the dashboard to load instantly without an initial API call.
|
|
|
|
|
|
|
|
---
|
|
|
|
### **2. The Backend: Resource Management**
|
|
|
|
*Located in the root directory.*
|
|
|
|
* **`model_cache.py`** (The 3-Tier Cache)
|
|
* **Role:** Thread-safe resource manager.
|
|
* **Tiers:** 1. Raw Files (RAM), 2. Incremental States (Partial LoRA stacks), 3. Final Results (Patched Models).
|
|
|
|
|
|
* **`conditioning_cache.py`** (The Prompt Cache)
|
|
* **Role:** Caches CLIP text encodings to disk.
|
|
* **Key Logic:** Hashes `(Prompt + CLIP State + LoRA Config)` to ensure validity.
|
|
|
|
|
|
* **`batch_encoding.py`** (The Accelerator)
|
|
* **Role:** Bulk prompt encoder.
|
|
* **Key Logic:** Scans the grid for all prompts using the current model and encodes them in one massive GPU batch.
|
|
|
|
|
|
|
|
---
|
|
|
|
### **3. The Frontend: ComfyUI Integration**
|
|
|
|
*Located in `/web/`.*
|
|
|
|
* **`dashboard.js`**
|
|
* **Role:** Registers the Dashboard node. Listens for server events to update the iframe.
|
|
|
|
|
|
* **`config_builder.js`**
|
|
* **Role:** Registers the Builder node. Provides the complex UI for creating JSON configs.
|
|
|
|
|
|
* **`smart_json_text.js`**
|
|
* **Role:** Registers the JSON node. Adds syntax highlighting and validation.
|
|
|
|
|
|
|
|
---
|
|
|
|
### **4. The Frontend: The Dashboard SPA**
|
|
|
|
*Located in `/resources/`. This is the "App" users interact with.*
|
|
|
|
* **`logic_init.js`** (The Bootstrapper)
|
|
* **Role:** Main Entry Point.
|
|
* **Key Logic:**
|
|
* **`initDashboard()`:** The first function called.
|
|
* **Data Injection:** detects if `fullManifest` exists (injected by Python). If not, it attempts to fetch it (View Mode).
|
|
* **Lifecycle:** Calls `initLogicState()` -> `applyPipeline()` -> `initVirtualScroller()` -> `initGlobalEvents()`.
|
|
|
|
|
|
|
|
|
|
* **`logic_state.js`** (The Brain)
|
|
* **Role:** Central State Store (Redux-style).
|
|
* **Key Logic:**
|
|
* **`State` Object:** Holds `items` (all images), `filteredItems` (visible), `selection` (active card), and `favorites`.
|
|
* **Triple JSON Lists:** Manages the logic for the "Accepted", "Favorites", and "Rejected" JSON bars at the bottom of the UI.
|
|
* **Persistence:** Saves user preferences (Sort Order, Column Count) to `localStorage` so they persist across reloads.
|
|
|
|
|
|
|
|
|
|
* **`logic_events.js`** (The Handler)
|
|
* **Role:** Interaction & API Bridge.
|
|
* **Key Logic:**
|
|
* **Keyboard Shortcuts:** Maps `Arrow Keys` (Pan), `Space` (Scroll), `+/-` (Zoom), `F` (Fit).
|
|
* **API Calls:** Uses `fetch` to hit endpoints like `/config_tester/save_manifest` (when you star/reject an image) and `/config_tester/delete_session`.
|
|
* **Live Updates:** Listens for the `executed` event from ComfyUI to trigger a soft-refresh of the image list.
|
|
|
|
|
|
|
|
|
|
* **`logic_virtual.js`** (The Engine)
|
|
* **Role:** Virtual Scroller.
|
|
* **Key Logic:** Calculates viewport geometry to render only the ~20 visible cards out of thousands, enabling high performance.
|
|
|
|
|
|
* **`logic_pipeline.js`** (The Processor)
|
|
* **Role:** Filtering & Sorting.
|
|
* **Key Logic:** Transforms the raw item list based on active filters (Model, Sampler, etc.) before passing it to the virtual scroller.
|
|
|
|
|
|
* **`logic_ui.js`** (The Renderer)
|
|
* **Role:** DOM Manipulation.
|
|
* **Key Logic:** Generates the HTML for individual cards and the "Revise" modal.
|
|
|
|
|
|
* **`logic_utils.js`** (The Helpers)
|
|
* **Role:** Utilities.
|
|
* **Key Logic:** Debouncers, formatters, and helper functions.
|
|
|
|
|
|
|
|
---
|
|
|
|
### **Summary of Data Flow**
|
|
|
|
1. **User Config:** You set parameters in the **Sampler Node** (Python).
|
|
2. **Expansion:** `generation_orchestrator.py` expands this into a list of jobs.
|
|
3. **Generation:** The backend loops through jobs, using **ModelCache** and **ConditioningCache** for speed.
|
|
4. **Storage:** Images are saved to disk; metadata is appended to `manifest.json`.
|
|
5. **Compilation:** `html_generator.py` reads the `manifest.json` and all `.js` files in `/resources/`, baking them into a single `dashboard_html` string.
|
|
6. **Display:** The **Dashboard Node** (JS) renders this HTML in an iframe.
|
|
7. **Boot:** `logic_init.js` wakes up, loads the data into `logic_state.js`, and `logic_virtual.js` starts rendering cards.
|
|
8. **Interaction:** You click "Favorite" in the UI -> `logic_events.js` sends an API request to `__init__.py` -> Python updates `manifest.json` on disk. |