README.md

metadata

title: Flux Microscopy Image Enhancement
emoji: 🔬
colorFrom: blue
colorTo: pink
sdk: gradio
sdk_version: 6.3.0
app_file: app.py
pinned: false
license: apache-2.0

🔬 Flux Microscopy Image Enhancement

An AI-powered microscopy image enhancement tool using the FLUX.2 model. This application provides intelligent image enhancement while preserving cellular structures and fine details.

Available in two versions:

• 🌐 Web UI (Gradio): Interactive web interface with drag-and-drop support
• ⌨️ CLI (Command Line): Batch processing tool for automation and scripting

✨ Features

• Batch Processing: Process multiple images at once or entire archived folders
• Archive Support: Upload ZIP or 7Z files containing multiple images
• Smart Enhancement: AI-powered enhancement using FLUX.2-dev with quantization (4-bit)
• Quality Metrics: Automatic calculation of PSNR and SSIM to evaluate enhancement quality
• Custom Prompts: Customize the enhancement behavior with natural language prompts
• Adjustable Parameters: Fine-tune guidance scale and inference steps for optimal results
• Structured Output: Download results with _flux suffix maintaining original directory structure

🚀 Quick Start

1. Upload Images: Upload individual images (JPG, PNG, BMP, TIFF) or compressed archives (ZIP, 7Z)
2. Customize (Optional): Adjust the enhancement prompt and parameters if needed
3. Process: Click "Enhance Images" and wait for processing to complete
4. Download: Get your enhanced images as a ZIP file with quality metrics

🖼️ Supported Formats

Input Formats

• Images: .jpg, .jpeg, .png, .bmp, .tiff, .tif
• Archives: .zip, .7z (automatically extracts and processes all images inside)

Output Format

• All enhanced images are saved with _flux suffix (e.g., image.png → image_flux.png)
• Results packaged in a ZIP file maintaining original folder structure

🎯 Default Enhancement Settings

• Prompt: "enhance microscopy image with subtle improvements, gently increase cellular boundary clarity, preserve original morphological structure, maintain authentic texture patterns, minimal noise reduction while keeping fine details intact"
• Guidance Scale: 2.0 (conservative for natural enhancement)
• Inference Steps: 30 (balanced quality and speed)

📊 Quality Metrics

The application automatically calculates two important metrics for each enhanced image:

• PSNR (Peak Signal-to-Noise Ratio): Measures pixel-level similarity

  • Higher values indicate better quality

  • 30 dB is considered good

• SSIM (Structural Similarity Index): Measures structural similarity

  • Values range from 0 to 1

  • 0.9 is considered excellent

  • More aligned with human perception than PSNR

🔧 Parameters

Guidance Scale (1.0 - 5.0)

Controls the strength of the enhancement:

• Lower values (1.0-2.0): More conservative, stays closer to original
• Higher values (3.0-5.0): More creative, stronger enhancements
• Default: 2.0

Inference Steps (10 - 50)

Number of processing iterations:

• Fewer steps (10-20): Faster processing, lower quality
• More steps (30-50): Better quality, slower processing
• Default: 30

💻 Model Information

This application uses:

• Model: diffusers/FLUX.2-dev-bnb-4bit
• Quantization: 4-bit bitsandbytes quantization for efficient inference
• Precision: bfloat16 for optimal quality/performance balance

🛠️ Local Installation

# Clone the repository
git clone https://huggingface.co/spaces/yichuan-huang/flux-microscopy-image-enhancement
cd flux-microscopy-image-enhancement

# Install dependencies
pip install -r requirements.txt

# Run the web UI
python app.py

# Or use the CLI version
python enhance_cli.py -i input.jpg -o output/

⌨️ CLI Usage

For batch processing and automation, use the command-line interface:

# Basic usage
python enhance_cli.py -i input.jpg -o output/

# Process multiple images
python enhance_cli.py -i img1.jpg img2.png img3.tif -o output/

# Process entire directory (recursive)
python enhance_cli.py -i images_folder/ -o output/

# Custom parameters
python enhance_cli.py -i input.jpg -o output/ \
  --guidance-scale 3.0 \
  --steps 40 \
  --prompt "enhance cellular structure"

# Quiet mode (minimal output)
python enhance_cli.py -i input.jpg -o output/ --quiet

CLI Arguments

• -i, --input: Input path(s) - image files or directories (required)
• -o, --output: Output directory for enhanced images (required)
• -p, --prompt: Enhancement prompt (optional)
• -g, --guidance-scale: Guidance scale 1.0-5.0 (default: 2.0)
• -s, --steps: Inference steps 10-50 (default: 30)
• -q, --quiet: Quiet mode - minimal output

📋 Requirements

• Python 3.10+
• CUDA
• ~40GB GPU memory for model inference
• Dependencies listed in requirements.txt

🎓 Use Cases

• Microscopy image enhancement for research
• Cellular structure visualization
• Biological sample analysis
• Medical imaging preprocessing
• Scientific publication preparation

⚠️ Notes

• Processing time depends on image size, number of images, and selected parameters
• GPU acceleration is highly recommended for faster processing
• The model preserves original cellular structures while enhancing clarity
• First run may take longer due to model downloading and caching

📝 License

Apache 2.0

🤝 Contributing

Contributions, issues, and feature requests are welcome!

🔗 Links

• FLUX.2 Model
• Diffusers Library
• Gradio Documentation

---

Built with ❤️ using Gradio and 🤗 Hugging Face