██████ ██████ ██   ██  ████  ██████   ██   ██████ ██████ ██████ ██████ ██████ ██   ██ ██████ ██████ 
  ██   ██     ███  ██ ██     ██  ██  ████    ██   ██  ██ ██     ██       ██   ███  ██ ██     ██  ██ 
  ██   ████   ██ █ ██ ██ ███ ██████ ██  ██   ██   ██████ ████   ████     ██   ██ █ ██ ████   ██████ 
  ██   ██     ██  ███ ██  ██ ██ ██  ██████   ██   ██ ██  ██     ██       ██   ██  ███ ██     ██ ██  
  ██   ██████ ██   ██  ████  ██  ██ ██  ██ ██████ ██  ██ ██████ ██     ██████ ██   ██ ██████ ██  ██ 

❯ Enhance your images with FLUX.1 models

Built with the tools and technologies:

• Table of Contents
• Features
• Prerequisites
• Installation
• Usage
  • Arguments
  • Options
  • Examples
• Processing Modes
• Image Preparation
• Memory Optimization
• Error Handling
• Notes
• Project Roadmap
• Contributing
• License
• Acknowledgments

TengraiRefiner is a Python script for batch processing images using FLUX models with optional acceleration via Alimama Turbo or ByteDance Hyper LORA adapters. It is meant mainly to act as a refiner for images produced by Tengrai AI (www.tengrai.ai) but can be obviously used to enhance any image using Flux.dev models.

• Support for both single image and batch processing
• Multiple processing modes: Refiner, Redux, Depth, and ReJoy
• Automatic image captioning with MiaoshouAI's Florence-2 model
• Compatible with FLUX.1-dev, FLUX.1-Redux-dev, and FLUX.1-Depth-dev models
• Intelligent image scaling to SDXL-compatible resolutions
• Memory-efficient processing with automatic CPU offloading
• FP8 quantization support for optimal performance
• Detailed progress tracking with per-step information
• Configurable acceleration options (Alimama Turbo or ByteDance Hyper)
• Custom LoRA support with ability to apply before acceleration
• Adjustable denoise strength for refiner processing
• Option to scale down large images for more efficient processing
• CFG guidance scale adjustment
• Control over number of inference steps
• Option for random output filenames

Before running the script, ensure you have Python 3.x installed and the following dependencies:

torch>=2.6.0
diffusers==0.32.2
transformers>=4.35.0
safetensors>=0.4.0
python-dotenv>=1.0.0
Pillow>=10.0.0
tqdm>=4.66.0
huggingface-hub>=0.19.0
optimum-quanto
faker
multiformats
xformers>=0.0.25

1. Clone this repository or download the script
2. Install the required dependencies:

   pip install -r requirements.txt

The script can be run from the command line with various options:

python script.py <path> [options]

• path: Required. Path to input file or directory containing image files to process

• -a, --acceleration: Choose acceleration LORA (options: 'alimama', 'hyper', or 'none', default: 'none')
• -p, --prompt: Set a custom prompt (default: 'Very detailed, masterpiece quality') or use 'auto' for automatic captioning
• -m, --mode: Set mode of operation (options: 'refiner', 'redux', 'depth', 'rejoy', default: 'refiner')
• -t, --safetensor: Path to a Flux safetensor file to load transformer weights
• -s, --scale-down: Scale down the source image if above 1.5 megapixels
• -l, --lora: Path to a LoRA file to apply before acceleration
• -d, --denoise: Denoise strength for refine processing (default: 0.20)
• -c, --cfg: CFG strength for processing (default: 3.0)
• -e, --steps: Number of steps for processing (default: 25)
• -o, --output_dir: Specify output directory
• -r, --random-names: Use random docker-style names for output files

1. Process a single image with default settings:

   python script.py path/to/image.png

2. Process a directory of images with Hyper acceleration:

   python script.py path/to/directory -a hyper

3. Process images with automatic captioning and specific output directory:

   python script.py path/to/directory -p auto -o output/folder

4. Use depth mode with Alimama acceleration:

   python script.py path/to/directory -m depth -a alimama

5. Apply a custom LoRA and set denoise strength with random output names:

   python script.py path/to/directory -l path/to/lora.safetensors -d 0.30 -r

TengraiRefiner supports multiple processing modes:

• Refiner (default): Image-to-image refinement with adjustable strength
• Redux: Uses FLUX.1-Redux-dev model for specialized processing
• Depth: Generates depth map from input image and uses it for control
• ReJoy: Text-to-image generation mode that uses the input image resolution

Each mode has specific advantages for different use cases. When using acceleration (Alimama or Hyper), steps are automatically reduced to 10 for optimal performance.

The script includes intelligent image preparation:

• Images smaller than 1 megapixel are automatically upscaled to the nearest SDXL resolution
• Images larger than 1.5 megapixels can be scaled down (with the -s/--scale-down option)
• Aspect ratio is preserved during scaling
• Compatible with common SDXL resolutions (1024×1024, 1024×576, etc.)

The script includes several optimizations:

• Memory-efficient attention for SD-based models
• BFloat16 precision by default
• Automatic CPU offloading for components not actively in use
• Transformer quantization via optimum-quanto for reduced VRAM usage
• Option to load pre-quantized transformer models via safetensors
• Model freezing for reduced memory footprint
• VAE tiling and slicing for large images
• Attention slicing for better memory efficiency

• Skips already processed images unless random names are used
• Provides detailed error messages for failed processing attempts
• Validates input paths and arguments
• Continues processing remaining images if one fails
• Comprehensive debug output for troubleshooting

• Requires CUDA-capable GPU for optimal performance
• Progress bars show both overall batch progress and per-image step progress
• Environment variables can be configured via .env file
• Original file names are preserved in output unless random naming is enabled
• For very large images, consider using the -s/--scale-down option
• Supports processing images in PNG, JPG, JPEG, and WEBP formats

• Task 1: Support Refiner mode and Redux mode
• Task 2: Add support for custom LoRA files
• Task 3: Implement intelligent image scaling for optimal processing
• Task 4: Add FP8 quantization support
• Task 5: Add Depth and ReJoy processing modes
• Task 6: Implement automatic image captioning
• Task 7: Add random output file naming option
• Task 8: Implement memory optimization for Redux
• Task 9: Add batch size control for more efficient processing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests for the TengraiRefiner project.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.

This project is protected under the GNU GPLv3 License. For more details, refer to the LICENSE file.

• Black Forest Labs for the FLUX.1 models
• Alimama Creative for the FLUX.1-Turbo adapter
• ByteDance for the Hyper-SD acceleration adapter
• MiaoshouAI for the Florence-2 image captioning model
• Tengrai AI for the inspiration behind this refiner