Face Restore Advanced is a comprehensive and advanced face restoration node suite for ComfyUI, providing state-of-the-art face enhancement capabilities with intelligent quality assessment and model fallback systems. This is a complete refactoring and significant expansion of the original facerestore implementation, incorporating cutting-edge features for professional-quality face restoration.
🔥 Advanced Face Restoration Pipeline
- Dual Model Support: Full CodeFormer and GFPGAN integration with automatic model detection
- Intelligent Caching System: Shared cache for face processing results to optimize repeated operations
- Model Fallback System: Automatic fallback to alternative models when primary restoration fails quality checks
- Fidelity Control: Fine-grained CodeFormer fidelity parameter control (0.0-1.0)
🧠 Comprehensive Quality Assessment
- Multi-Metric Analysis: SSIM, artifact detection, color bleeding analysis, geometric distortion detection
- Face-Specific Quality Metrics: Skin texture analysis, facial landmark preservation, feature consistency
- Model-Specific Artifact Detection: Specialized detection for CodeFormer and GFPGAN artifacts
- Mouth Corner Artifact Detection: Advanced detection of corner-of-mouth artifacts common in face restoration
- Progressive Thresholding: Quality thresholds with gradual strictness levels (0.0-1.0)
🎯 Specialized Face Analysis
- 68-Point Landmark Detection: Detailed facial feature analysis and preservation scoring
- Skin Texture Quality Assessment: Advanced texture analysis using local binary patterns
- Eye and Mouth Region Analysis: Specialized quality assessment for critical facial features
- Color Consistency Analysis: Jensen-Shannon divergence for color distribution analysis
⚡ Performance Optimizations
- Intelligent Caching: Face detection and restoration results cached for efficiency
- Memory Management: Automatic cache size limiting and cleanup
- Robust Error Handling: Comprehensive error recovery with fallback mechanisms
- Tensor Optimization: Advanced tensor-to-image conversion with overflow protection
The main face restoration node with advanced quality control and fallback capabilities.
Parameters:
facerestore_model: The loaded face restoration model (CodeFormer or GFPGAN)image: Input image(s) for face restorationfacedetection: Face detection method (retinaface_resnet50, retinaface_mobile0.25, YOLOv5l, YOLOv5n)codeformer_fidelity: Fidelity parameter for CodeFormer (0.0-1.0, higher preserves more original details)quality_threshold: Quality threshold for accepting restoration (0.0-1.0, set to 0.0 to disable)enable_model_fallback: Enable automatic model fallback on quality failurefallback_model: Optional explicit fallback model
Extracts and crops detected faces from images.
Parameters:
image: Input image(s)facedetection: Face detection method
Extracts faces, restores them, and returns the cropped restored faces.
Parameters:
- Same as FaceRestoreCFWithModel but returns cropped faces instead of full images
Loads face restoration models with intelligent architecture detection.
Parameters:
model_name: Model file frommodels/facerestore_modelsdirectory
- Clone this repository to your ComfyUI custom nodes directory:
cd ComfyUI/custom_nodes
git clone https://github.com/flickleafy/facerestore_advanced.git- Install dependencies:
Windows (Portable): Run embedded_install.bat
Windows (Standard): Run install.bat
Linux/Mac: Run install.sh
If the automatic installation fails, manually install these dependencies:
pip install opencv-python scikit-image scipy dlibNote: If you encounter a "cv2 not found" error, ensure opencv-python is properly installed.
Place these models in ComfyUI/models/facerestore_models/:
CodeFormer:
- Download: codeformer.pth
GFPGAN:
- Download: GFPGANv1.4.pth
- Alternative versions available at GFPGAN Releases
These models are automatically downloaded on first use to ComfyUI/models/facedetection/:
RetinaFace Models:
YOLOv5 Face Models:
Face Parsing Model:
The quality threshold parameter provides fine-grained control over restoration acceptance:
- 0.0: Disable quality assessment (always accept restoration)
- 0.1-0.3: Very lenient (accept most restorations)
- 0.4-0.6: Balanced (recommended for most use cases)
- 0.7-0.8: Strict (only accept high-quality restorations)
- 0.9-1.0: Very strict (only accept exceptional restorations)
Enable automatic model fallback for optimal results:
- Set
enable_model_fallbacktoTrue - Optionally provide a
fallback_model(or let the system auto-determine) - If primary restoration fails quality checks, the system automatically tries the fallback model
- Best result is automatically selected based on quality metrics
Fine-tune the balance between restoration strength and detail preservation:
- 0.0: Maximum restoration, minimal original detail preservation
- 0.5: Balanced restoration (recommended starting point)
- 1.0: Maximum original detail preservation, minimal restoration
Choose the optimal detection method for your use case:
- retinaface_resnet50: Highest accuracy, slower processing
- retinaface_mobile0.25: Good accuracy, faster processing
- YOLOv5l: Large model, excellent detection capabilities
- YOLOv5n: Lightweight model, fastest processing
The system evaluates restoration quality using comprehensive metrics:
- SSIM (Structural Similarity): Measures overall image similarity
- Artifact Detection: Identifies restoration artifacts and noise
- Color Bleeding Analysis: Detects unnatural color mixing
- Geometric Distortion: Measures facial feature distortion
- Skin Texture Quality: Evaluates skin texture improvement
- Facial Feature Preservation: Measures landmark consistency
- Eye Region Analysis: Specialized eye area quality assessment
- Mouth Corner Artifacts: Detects common mouth corner issues
- CodeFormer Artifacts: Over-smoothing, skin uniformity issues
- GFPGAN Artifacts: Over-sharpening, checkerboard patterns
- Face processing results are automatically cached
- Cache key includes image content, model, and parameters
- Automatic cache size management (50 entry limit)
- Significant performance improvement for batch processing
- Automatic tensor cleanup after processing
- CUDA memory clearing for GPU acceleration
- Overflow protection in image conversions
- Robust error handling with graceful degradation
- Modular Design: Separate classes for face restoration, cropping, and model loading
- Smart Model Detection: Automatic CodeFormer/GFPGAN architecture identification
- Robust Tensor Handling: Advanced image-tensor conversion with error protection
- Comprehensive Logging: Detailed quality assessment reporting
- Graceful fallback on model loading failures
- Quality assessment error recovery
- Invalid value handling in image processing
- Memory overflow protection
- Type hints throughout codebase
- Comprehensive documentation
- Modular function design
- Extensive error checking
"cv2 not found" Error:
pip install opencv-python"SSIM calculation failed" Warning:
pip install scikit-imageMemory Issues with Large Batches:
- Reduce batch size
- Enable automatic fallback
- Lower quality thresholds
Poor Restoration Quality:
- Increase quality threshold
- Enable model fallback
- Try different face detection methods
- Adjust CodeFormer fidelity parameter
Enable detailed quality assessment logging by monitoring the console output. The system provides comprehensive metrics for each face restoration attempt.
We welcome contributions! Areas of particular interest:
- Additional quality assessment metrics
- New face detection methods
- Performance optimizations
- Model architecture support
- Documentation improvements
- ✨ Complete refactoring of face restoration pipeline
- ✨ Advanced quality assessment with 15+ metrics
- ✨ Intelligent model fallback system
- ✨ Comprehensive caching for performance optimization
- ✨ Mouth corner artifact detection
- ✨ Progressive quality thresholding
- ✨ Enhanced error handling and memory management
- ✨ Detailed quality reporting and analysis
- ✨ Model-specific artifact detection
- ✨ Facial landmark preservation analysis
This project builds upon and integrates several excellent open-source projects:
- CodeFormer: sczhou/CodeFormer
- GFPGAN: TencentARC/GFPGAN
- FaceXLib: Face detection and restoration utilities
- ComfyUI: comfyanonymous/ComfyUI
- Original FaceRestore Node: facerestore custom node
Special thanks to the computer vision and machine learning research communities for their groundbreaking work in face restoration and quality assessment.
This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for full details.
Copyright © 2025 flickleafy
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.