README.md

---
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](https://huggingface.co/diffusers/FLUX.2-dev-bnb-4bit)
- **Quantization**: 4-bit bitsandbytes quantization for efficient inference
- **Precision**: bfloat16 for optimal quality/performance balance

## 🛠️ Local Installation

```bash
# 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:

```bash
# 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](https://huggingface.co/diffusers/FLUX.2-dev-bnb-4bit)
- [Diffusers Library](https://github.com/huggingface/diffusers)
- [Gradio Documentation](https://www.gradio.app/docs)

---

Built with ❤️ using Gradio and 🤗 Hugging Face