From c64ba671651e6a0bf4026871028e2b39c160b2d0 Mon Sep 17 00:00:00 2001 From: Marco Date: Tue, 14 Apr 2026 16:57:53 -0300 Subject: [PATCH] docs: restructure README and add multi-MD category documentation --- docs/CHARACTER_AND_ANIMATION.md | 15 +++ docs/FILTERS.md | 15 +++ docs/IMAGE_PROCESSING.md | 27 +++++ docs/INFERENCE.md | 23 ++++ docs/PIXEL_ART.md | 14 +++ docs/TRELLO_INTEGRATION.md | 13 +++ readme.md | 196 +++++--------------------------- 7 files changed, 134 insertions(+), 169 deletions(-) create mode 100644 docs/CHARACTER_AND_ANIMATION.md create mode 100644 docs/FILTERS.md create mode 100644 docs/IMAGE_PROCESSING.md create mode 100644 docs/INFERENCE.md create mode 100644 docs/PIXEL_ART.md create mode 100644 docs/TRELLO_INTEGRATION.md diff --git a/docs/CHARACTER_AND_ANIMATION.md b/docs/CHARACTER_AND_ANIMATION.md new file mode 100644 index 0000000..5a0dacd --- /dev/null +++ b/docs/CHARACTER_AND_ANIMATION.md @@ -0,0 +1,15 @@ +# ๐Ÿ‘พ Character & Animation + +Tools for generating character descriptions, prompts, and corresponding sprite-sheet animations. + +#### Character Randomizer +Generates random character attributes for fighting game characters (gender, fighting style, nationality, etc.) utilizing a deterministic seed-based system. + +#### Character Constructor +Constructs detailed, rich character prompts from the attributes provided by the Randomizer to be used directly in AI image generation workflows. + +#### Fighting Game Character Generator +Creates character sprites and animations from character parameters and pose settings. + +#### Walking Pose Generator +Generates walking animation frame sequences given a base character and walk cycle settings. diff --git a/docs/FILTERS.md b/docs/FILTERS.md new file mode 100644 index 0000000..d3eff54 --- /dev/null +++ b/docs/FILTERS.md @@ -0,0 +1,15 @@ +# ๐Ÿ–Œ๏ธ GIMP-Style Filters + +Professional-grade image post-processing filters modeled directly after GIMP and GEGL implementations for high-quality mathematical adjustments. + +#### Adaptive Noise Filter +Applies frequency-aware noise (Gaussian or Uniform) that naturally adapts to image contentโ€”providing more noise structurally on edges and less on flat gradients. + +#### RGB Noise (GEGL-like) +RGB channel noise filter perfectly matching GIMP's GEGL implementation. Provides separated channel noise with correlation tracking. + +#### CIE LCH Noise (GEGL-like) +A perceptually uniform noise filter injected directly into the CIE LCH color space. Very useful for simulating natural film grain and distributing noise across Lightness, Chroma, and Hue axes. + +#### Mean Curvature Blur (GEGL-like) +An edge-preserving blur filter based on surface curvature analysis. It smooths flat areas iteratively without blurring critical structural edges. diff --git a/docs/IMAGE_PROCESSING.md b/docs/IMAGE_PROCESSING.md new file mode 100644 index 0000000..f69c5af --- /dev/null +++ b/docs/IMAGE_PROCESSING.md @@ -0,0 +1,27 @@ +# ๐Ÿ–ผ๏ธ Image Processing & Loaders + +This category focuses on efficient and robust image loading, batch processing, and dataset preparation. + +#### Load Images (Original Size) +Loads all images from a directory while preserving their original dimensions. Compatible with RebatchImages and supports common formats. + +#### Load Image (Remove Alpha) +Loads an image from a file path and removes the alpha channel, compositing over a white background. + +#### Remove Alpha Channel +Removes the alpha channel from already loaded images in a workflow, compositing over a white background. + +#### Custom Crop +Crops images with specific positioning options (Modes: center, left, right, top, bottom). + +#### Smart Resize with Border Fill +Intelligently resizes images while filling missing areas with border colors using mean or mode for detection. + +#### Nearest Neighbor Upscale +Perfect 1:1 scaling for pixel art without interpolation artifacts (scale factor 1-8). + +#### Get Last Image +Utility node that separates and returns only the last image from a batch. + +#### Image Type Detector +Utility that detects if an input is a single image or batch, redirecting the workflow and providing type flags for debugging or routing. diff --git a/docs/INFERENCE.md b/docs/INFERENCE.md new file mode 100644 index 0000000..77d0481 --- /dev/null +++ b/docs/INFERENCE.md @@ -0,0 +1,23 @@ +# ๐Ÿš€ Native Inference Suite + +A robust, self-contained suite of computer vision nodes utilizing embedded Python integrations. It automatically downloads its own models and handles zero-shot segmentation and detection internally, keeping workflows clean. + +> **Note**: These components do not rely on large external node packs and are fully embedded within the node logic. + +### ๐Ÿ” Model Loaders +- **AnotherLoadYOLO**: Downloads and loads Ultralytics models (`v8`, `11`, `pose`, `seg`). Includes built-in support for YOLO size presets. +- **AnotherLoadSAM2**: Downloads and loads META's Segment Anything 2 models (`hiera_tiny` through `large`). Supports modes for `single_image` estimation or `video` propagation. +- **AnotherLoadDepth**: Downloads and loads Depth-Anything-V3 pipelines seamlessly. + +### ๐Ÿ“ Inference Engines +- **AnotherYOLOInference**: Performs standard object or pose detection. Returns bounding boxes, keypoints, tracking IDs, labels, and debugging frames with full visual skeletons. +- **AnotherSAM2Inference**: Single-image zero-shot segmentation supporting coordinates and bounding boxes. +- **AnotherSAM2VideoAddPoints**: Video tracking initialization. Maps point prompts natively onto a specific frame index to kickstart stateful segmentation tracking. +- **AnotherSAM2VideoPropagate**: Tracks marked subjects linearly across all frames using the `SAM2VideoPredictor` backend. + +### ๐Ÿ› ๏ธ Geometric Utility +- **AnotherBBoxToPoints**: Parses YOLO bounding boxes into format-friendly points for SAM 2 mapping. +- **AnotherPoseToPoints**: Transforms YOLO COCO-topology keypoints into targeted point lists using body-map dropdown menus (e.g., `face`, `left_arm`, `both_legs_only`). +- **AnotherImageToMask / AnotherMaskToImage**: Clean converters bridging binary masks to grayscale RGB imagery. +- **AnotherMaskMath**: Executes math operations dynamically on masks (`add`, `subtract`, `multiply`, `logical_and`/`or`). +- **AnotherMaskBlur**: Quick standalone structural blur for mask feathering. diff --git a/docs/PIXEL_ART.md b/docs/PIXEL_ART.md new file mode 100644 index 0000000..f3540e6 --- /dev/null +++ b/docs/PIXEL_ART.md @@ -0,0 +1,14 @@ +# ๐ŸŽจ Pixel Art Tools + +A dedicated suite of nodes for transforming and standardizing images into pixel art formats. + +#### Pixel Art Normalizer +Normalizes images into a consistent pixel art style. +- **Features:** Automatic grid detection, color quantization. +- **Outputs:** Normalized image, detected block size, true 1:1 pixel art. + +#### Pixel Art Converter +Advanced single-image pixel art conversion with customizable palette and resolution settings. + +#### Pixel Art Converter (Parallel) +Multi-threaded version of the pixel art converter for fast batch processing. diff --git a/docs/TRELLO_INTEGRATION.md b/docs/TRELLO_INTEGRATION.md new file mode 100644 index 0000000..d58cace --- /dev/null +++ b/docs/TRELLO_INTEGRATION.md @@ -0,0 +1,13 @@ +# ๐Ÿ“‹ Trello Integrations & Prompt Management + +A specialized benchmarking and prompt fetching suite designed to use Trello boards as active logic or dataset drivers. + +### ๐Ÿ—ƒ๏ธ Trello Browser +A rich graphical node providing an advanced embedded web interface (via JavaScript). The Trello Browser lists active cards on a specific board/list, displaying their descriptions as prompts, and dynamically loads their image attachments natively into ComfyUI. +- You can manually select what Prompt-Image pair to load into an ongoing generation. +- Highly useful for inspecting dataset tests before starting automated jobs. + +### ๐Ÿ”„ Trello Prompt Loader +A headless, index-based iterator meant for automated benchmarking scripts. +- Designed to run systematically in bulk using ComfyUI batch queues or API integrations. +- Steps through a specified Trello list, extracting card names and desc payloads one-by-one by index. diff --git a/readme.md b/readme.md index ff71cc9..df96ddc 100644 --- a/readme.md +++ b/readme.md @@ -1,183 +1,41 @@ -# ComfyUI AnotherUtils - Complete Node Collection +# ComfyUI AnotherUtils -A comprehensive collection of custom nodes for ComfyUI, featuring image processing, animation tools, character generation, and advanced filters inspired by GIMP/GEGL. +A comprehensive and standalone collection of robust custom nodes for ComfyUI. +AnotherUtils focuses on providing heavy-lifting utilities without requiring massive external dependencies. It encompasses advanced AI pipelines natively, classic pixel transformations, character animations, professional GEGL/GIMP filters, operations, and robust dataset preparation functions. -## Installation +## ๐Ÿ“š Documentation + +The documentation has been categorized into multiple modules to keep things clean. Click on any category below for a detailed list and explanation of the nodes available: + +- [๐Ÿš€ Native Inference Suite](docs/INFERENCE.md) - YOLO Detection, SAM 2 (Image & Video), DepthAnything, and bounding box geometric utilities. +- [๐Ÿ“‹ Trello Integrations](docs/TRELLO_INTEGRATION.md) - Interactive web-browser nodes and automated benchmark loaders targeting Trello boards. +- [๐Ÿ–ผ๏ธ Image Processing](docs/IMAGE_PROCESSING.md) - Batch-capable image loaders, boundary-aware resizers, precision croppers, and type-detection logic. +- [๐ŸŽจ Pixel Art Tools](docs/PIXEL_ART.md) - True mathematical pixel art normalization, scaling, and color quantization. +- [๐Ÿ‘พ Character & Animation](docs/CHARACTER_AND_ANIMATION.md) - Randomizer grids, prompt builders, sprite creators, and walking pose engines. +- [๐Ÿ–Œ๏ธ GIMP-Style Filters](docs/FILTERS.md) - High-quality mathematical filters like Mean Curvature Blur, Adaptive Frequency Noise, and LCH processing logic. + +## ๐Ÿ“ฆ Installation 1. Navigate to your ComfyUI `custom_nodes` directory 2. Clone this repository: ```bash -git clone https://github.com/yourusername/ComfyUI-AnotherUtils.git +git clone https://github.com/marcoc2/ComfyUI-AnotherUtils.git ``` 3. Restart ComfyUI -## Node Categories +*(Note: Essential weights like YOLO, SAM2, and DepthAnything models are automatically fetched and downloaded into the `models/another_utils` or generic `models/sub-folder` namespaces seamlessly on their first run. No manual weight hunting required!)* -### ๐Ÿ–ผ๏ธ Image Processing & Loaders +## ๐Ÿงฉ Features +- **Zero-Dependency Core Models**: The Inference Suite runs logic locally using internal packages heavily mimicking their official counterparts, preventing dependency hell against major node packs. +- **Batch Processing**: Most nodes scale into dimensional batches instantly for video outputs or dataset rendering. +- **Memory Efficient**: Internal GPU structures and tensors are forcefully released or managed via JIT routines for optimal layout. +- **Deterministic**: Complete seed-based structural operations for perfect tracking tests. -#### Load Images (Original Size) -Loads all images from a directory while preserving their original dimensions. -- **Input:** Directory path -- **Output:** Images in original sizes -- **Features:** Compatible with RebatchImages, supports common formats +## ๐Ÿค Contributing +Issues and pull requests are welcome! Please follow the existing code paradigms natively embedded inside. -#### Load Image (Remove Alpha) -Loads an image from file path and removes alpha channel, compositing over white background. -- **Input:** Image file path -- **Output:** RGB image without transparency - -#### Remove Alpha Channel -Removes alpha channel from already loaded images, compositing over white background. -- **Input:** RGBA image -- **Output:** RGB image without transparency - -#### Custom Crop -Crops images with specific positioning options. -- **Inputs:** Image, crop dimensions, position mode -- **Modes:** center, left, right, top, bottom - -#### Smart Resize with Border Fill -Intelligently resizes images while filling missing areas with border colors. -- **Inputs:** Image, target size, sampling method -- **Color Methods:** mean or mode for border detection - -#### Nearest Neighbor Upscale -Perfect upscaling for pixel art without interpolation artifacts. -- **Input:** Image, scale factor (1-8) -- **Output:** Crisp upscaled image - -#### Get Last Image -Utility node that returns the last image from a batch. -- **Input:** Image batch -- **Output:** Single image (last in sequence) - -### ๐ŸŽจ Pixel Art Tools - -#### Pixel Art Normalizer -Normalizes images into consistent pixel art style with grid detection. -- **Inputs:** Image, block size (auto-detect if 0), color count -- **Outputs:** Normalized image, detected block size, true 1:1 pixel art -- **Features:** Automatic grid detection, color quantization - -#### Pixel Art Converter -Advanced pixel art conversion with customizable settings. -- **Inputs:** Image, target resolution, color palette options -- **Output:** Converted pixel art image - -#### Pixel Art Converter (Parallel) -Multi-threaded version of the pixel art converter for batch processing. -- **Input:** Image batch -- **Output:** Batch of converted pixel art images - -### ๐ŸŽฎ Character Generation - -#### Character Randomizer -Generates random character attributes for fighting game characters. -- **Input:** Random seed -- **Outputs:** 10 character attributes (gender, fighting style, nationality, etc.) -- **Features:** Deterministic randomization, extensive attribute lists - -#### Character Constructor -Constructs detailed character prompts from selected attributes. -- **Inputs:** All character attributes (gender, style, nationality, etc.) -- **Outputs:** Complete character prompt, formatted attribute summary -- **Use Case:** Perfect for AI character generation workflows - -### ๐Ÿƒโ€โ™‚๏ธ Animation Tools - -#### Fighting Game Character Generator -Creates character sprites and animations for fighting games. -- **Inputs:** Character parameters, pose settings -- **Output:** Character sprite sheets - -#### Walking Pose Generator -Generates walking animation frames with customizable parameters. -- **Inputs:** Base character, walk cycle settings -- **Output:** Animation frame sequence - -### ๐ŸŽจ GIMP-Style Filters - -#### Adaptive Noise Filter -Applies frequency-aware noise that adapts to image content. -- **Inputs:** Image, noise strength, adaptation strength, edge threshold -- **Features:** More noise on edges, less on flat areas -- **Types:** Gaussian or Uniform noise - -#### RGB Noise (GEGL-like) -RGB channel noise filter matching GIMP's GEGL implementation. -- **Inputs:** Image, noise amount per channel, correlation settings -- **Output:** Image with channel-specific noise - -#### CIE LCH Noise (GEGL-like) -Perceptually uniform noise in CIE LCH color space. -- **Inputs:** Image, lightness/chroma/hue noise amounts -- **Features:** Perceptually natural noise distribution - -#### Mean Curvature Blur (GEGL-like) -Edge-preserving blur based on surface curvature analysis. -- **Inputs:** Image, blur radius, iterations -- **Features:** Preserves edges while smoothing flat areas - -#### Image Type Detector -Detects if input is single image or batch and provides appropriate outputs. -- **Input:** Image/batch -- **Outputs:** Single image, batch images, count, type flag -- **Use Case:** Workflow routing and debugging - -## Usage Examples - -### Character Generation Workflow -``` -CharacterRandomizer -> CharacterConstructor -> [AI Image Generation] -``` - -### Pixel Art Pipeline -``` -LoadImagesOriginal -> PixelArtNormalizer -> NearestUpscale -> [Output] -``` - -### Advanced Image Processing -``` -LoadImages -> AdaptiveNoise -> MeanCurvatureBlur -> [Final Processing] -``` - -### Animation Creation -``` -CharacterGenerator -> WalkingPoseGenerator -> [Animation Export] -``` - -### Dataset Preparation -``` -LoadImagesOriginal -> CustomCrop -> SmartResize -> RemoveAlpha -> [Training] -``` - -## Node Count -**Total: 19 Nodes** -- 8 Image Processing & Loaders -- 3 Pixel Art Tools -- 2 Character Generation -- 2 Animation Tools -- 5 GIMP-Style Filters - -## Dependencies -- NumPy -- OpenCV (cv2) -- scikit-learn -- PIL/Pillow -- PyTorch (provided by ComfyUI) - -## Features -- **Batch Processing:** Most nodes support batch operations -- **Memory Efficient:** Optimized for large image sets -- **ComfyUI Native:** Full compatibility with ComfyUI ecosystem -- **Deterministic:** Seed-based operations for reproducible results -- **Professional Grade:** GIMP/GEGL equivalent filters - -## Contributing -Issues and pull requests welcome! Please follow the existing code style and include tests for new features. - -## License -MIT License - See LICENSE file for details +## ๐Ÿ“œ License +MIT License - See LICENSE file for details. --- -*Created by marcoags - Version 1.0.0* \ No newline at end of file +*Created by marcoags* \ No newline at end of file