# SATA Utility Node Suite for ComfyUI **Author:** Satadal **Version:** 2.0 **License:** MIT **Repository:** https://github.com/SatadalAI/SATA_UtilityNode --- ## πŸš€ Overview SATA Utility Node Suite is a collection of custom nodes for [ComfyUI](https://github.com/comfyanonymous/ComfyUI) designed to enhance your image processing and workflow experience. It includes: - **Upscale Machine:** High-quality model-based image upscaling with Frequency-Split SR and Blue Noise injection. - **Prompt Machine (Eight-Category Framework):** Professional structured prompting with JSON output support. - **Prompt Style Machine:** Easy prompt selection from a CSV for positive/negative prompt workflows. - **Touchpad Pan & Zoom:** Seamless navigation for large images in the ComfyUI preview panel. - **Resolution Machine:** Quick selection of model-specific image resolutions with intelligent Megapixel scaling. - **Save Image w/Metadata:** Saving images with metadata and with different file formats. - **Prompt Autocomplete:** Text widget with highly optimized subsequence fuzzy autocompletion. - **Latent Machine:** Advanced noise generation (Power-Law, Plasma, Blue, Offset) supporting both 4-channel and 16-channel modern architectures. - **Preview Machine:** Privacy-focused image preview node with auto-hide and hover-to-reveal functionality. --- ## 🧩 Node Features ### πŸ–ΌοΈ Upscale Machine - **Model-based Upscaling:** Uses custom or pre-trained models from the `upscale_models` folder. - **Frequency-Split SR:** Separates image into base colors (low frequencies) and sharp edges (high frequencies). The neural network only upscales edges, while a bicubic algorithm scales colors, eliminating "plastic/waxy" looks and edge halos. - **Blue Noise Injection:** Adds high-frequency micro-textures (`inject_noise_for_realism`) during upscaling. Automatically activates when using a chained model to fix the "smoothness" problem in low-step/distilled models like SDXL Turbo. - **Aspect Ratio Preserving Rescale:** Output size is always original size Γ— rescale factor. - **CPU-based Rescaling:** Efficient resizing using OpenCV. - **Rounding Modulus:** Ensures output dimensions seamlessly align with UNet architectural constraints. ### πŸ’¬ Prompt Machine (Eight-Category Framework) - **Structured Prompting:** Dedicated input boxes for `subject`, `pose_and_expression`, `secondary_subject`, `background_and_environment`, `lighting`, `style`, `creative_hook`, and `technical` details following an inside-out spatial sequence. - **JSON Output Mode:** Toggle `json_output` to compile the slots into a strict JSON string, perfect for piping into LLM rewriting nodes or API pipelines. - **Autocomplete Ready:** Fully integrated with the autocomplete systemβ€”just type `#` in any slot to trigger the smart tag popup! - **Universal Model Compatibility:** Formats naturally for FLUX, SD3.5, SDXL, SD 1.5, PixArt, and LLM expansion pipelines. ### πŸ’¬ Prompt Style Machine (Legacy) - **CSV-based Prompt Selection:** Select prompt sets from a CSV file (`prompts.csv`). - **Clean Output:** Outputs the positive prompt string with a live, enlarged text preview inside the node. ### πŸ–±οΈ Touchpad Pan & Zoom - **Preview Navigation:** Enables smooth pan and zoom for large images in the ComfyUI preview panel. - **User Experience:** Makes inspecting high-res outputs fast and intuitive. ### πŸ“ Resolution Machine - **Intelligent Megapixel Scaling:** Uses a target Megapixel slider to automatically calculate the exact width/height required to hit the target while perfectly preserving your chosen aspect ratio. Rounds to the nearest multiple of 8. - **Model-aware Resolution Selection:** Choose from a list of recommended resolutions for each supported model (SD1.5, SDXL, Flux.1 & Flux.2, SD3 & SD3.5, Ideogram 4, Lumina, Qwen-Image, Z-Image Turbo, Hunyuan-DiT, and Video Models like Wan2.2, HunyuanVideo, Mochi-1, LTX-Video). --- ### πŸ’Ύ Save Image w/Metadata - **Single path+filename input:** Provide a single required `path_and_filename` string. - **Supported formats:** PNG, JPEG (saved as .jpg), WEBP (choose with the `extension` dropdown). - **Automatic folder creation:** Any missing folders in the provided path are created automatically. - **Metadata embedding:** PNG files receive tEXt entries (parameters/prompt). JPEG/WEBP receive EXIF UserComment where possible. - **Placeholder resolution:** Filenames and paths accept `%...%` placeholders which are resolved from the node's `prompt` dictionary. - **Collision-safe saving:** Automatically appends numerical suffixes to avoid overwriting. ### ✍️ Prompt Autocomplete - **Subsequence Fuzzy Matching:** Ultra-fast, highly optimized fuzzy search with rank-based scoring. - **Autocompletion:** Type `#` (configurable) to trigger a popup with suggestions from CSV/JSON files in the `prompt` folder. Supports strict 100-item render limits to prevent UI lag. - **Random Selection:** Select `🎲 Random` to insert a random item from a category. - **Global Mode:** Optional setting to enable autocompletion on ALL text widgets in ComfyUI. ### 🌌 Latent Machine - **Advanced Noise Generation:** Initialize latents with specific noise patterns: - **Gaussian (White):** Standard noise, good for sharp details. - **Blue (High-Frequency):** Enhances detail and textures. - **Pink (1/f) / Brown (1/fΒ²):** Photorealism, nature, anime backgrounds. - **Perlin / Plasma:** Fluid landscapes, sci-fi, abstract terrains. - **High-Contrast Offset Noise:** Toggle `high_contrast` to inject a `0.1` mean shift to the starting noise, allowing the model to generate pure blacks (pitch-black nights) and blown-out whites (snowstorms). - **Auto 16-Channel Detection:** Automatically provisions the correct latent depth for modern architectures (Flux, SD3, Lumina, Z-Image). - **Reproducibility:** Full seed support for consistent noise generation. ### πŸ‘οΈ Preview Machine - **Privacy-Focused Preview:** Image preview node that hides content by default. - **Hover to Reveal / Auto-Hide:** Simply hover over the node to temporarily reveal the image. - **Global Hide Mode:** Optional setting to hide ALL preview nodes in the workflow (Settings β†’ SATA Utility: Global Hide Previews). ## πŸ“¦ Installation 1. Clone or download this repository into your ComfyUI `custom_nodes` directory: ```sh git clone https://github.com/SatadalAI/SATA_UtilityNode.git ``` 2. (Optional) Install dependencies if not already present: ```sh pip install -r requirements.txt ``` 3. Restart ComfyUI. --- **Settings:** - **Trigger Character:** Change the character that opens the popup (default: `#`). - **Global Mode:** Enable autocompletion for all text widgets in ComfyUI (default: `false`). ## πŸ“ License MIT License --- ## πŸ”— Links - [ComfyUI](https://github.com/comfyanonymous/ComfyUI)