smilar-image-colorization--pytorch

# 🎨 AI Image Colorization

<div align="center">

![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)
![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-orange.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Stars](https://img.shields.io/github/stars/canuzlas/image-colorization?style=social)

**Transform black & white photos into vibrant color images using deep learning**

[🚀 Quick Start](#-quick-start) •
[📖 Documentation](#-documentation) •
[🎯 Demo](#-demo) •
[🤝 Contributing](#-contributing)

</div>

---

## ✨ Overview

This project uses state-of-the-art deep learning techniques to automatically colorize grayscale images. Built with PyTorch and U-Net architecture, it converts L*a*b* color space representations to produce realistic and vibrant colorizations.

### 🎯 Key Features

- 🤖 **U-Net Architecture**: Advanced encoder-decoder with skip connections
- 🎨 **LAB Color Space**: Perceptually uniform color representation
- 🚀 **Real-time Demo**: Interactive Streamlit web application
- 🔗 **REST API**: FastAPI endpoints for production deployment
- 🐳 **Docker Ready**: Containerized for easy deployment
- 📊 **Comprehensive Metrics**: PSNR, SSIM, and MSE evaluation

## 🚀 Quick Start

### One-Command Setup
```bash
git clone https://github.com/canuzlas/image-colorization.git
cd image-colorization
./setup.sh
```

### Manual Setup
```bash
# Clone repository
git clone https://github.com/canuzlas/image-colorization.git
cd image-colorization

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Setup project structure
make setup
```

## 🎯 Demo

### 🖥️ Web Interface
```bash
# Launch Streamlit demo
streamlit run app.py
```
Visit `http://localhost:8501` to try the interactive demo!

### 🔗 API Server
```bash
# Start FastAPI server
python src/api.py
```
API documentation available at `http://localhost:8000/docs`

### 🐳 Docker
```bash
# Build and run with Docker
docker-compose up
```

## 📊 Model Performance

| Metric | Score | Description |
|--------|-------|-------------|
| **PSNR** | 28.5 dB | Peak Signal-to-Noise Ratio |
| **SSIM** | 0.85 | Structural Similarity Index |
| **MSE** | 0.012 | Mean Squared Error |

## 🛠️ Usage Examples

### Command Line Interface
```bash
# Colorize single image
python src/inference.py \
  --model models/best_checkpoint.pth \
  --input path/to/grayscale.jpg \
  --output colorized.jpg

# Batch processing
python src/inference.py \
  --model models/best_checkpoint.pth \
  --input input_folder/ \
  --output output_folder/ \
  --batch

# Create comparison
python src/inference.py \
  --model models/best_checkpoint.pth \
  --input image.jpg \
  --output comparison.jpg \
  --comparison
```

### Python API
```python
from src.inference import ColorizationInference

# Initialize model
colorizer = ColorizationInference('models/best_checkpoint.pth')

# Colorize image
colorized = colorizer.colorize_image('grayscale.jpg', 'colorized.jpg')
```

## 🏗️ Project Structure

```
image-colorization/
├── 📁 src/                     # Source code
│   ├── 🧠 models/              # Model architectures
│   ├── 🔄 preprocessing/       # Data preprocessing
│   ├── 🛠️ utils/               # Utility functions
│   ├── 🚀 train.py             # Training script
│   ├── 🎯 inference.py         # Inference script
│   └── 🌐 api.py               # FastAPI endpoints
├── 📊 data/                    # Datasets
├── 🤖 models/                  # Trained models
├── 📈 results/                 # Output results
├── 📓 notebooks/               # Jupyter notebooks
├── ⚙️ config/                  # Configuration files
├── 🎨 app.py                   # Streamlit demo
├── 🐳 Dockerfile               # Docker configuration
└── 📋 requirements.txt         # Dependencies
```

## 🔬 Technical Details

### Model Architecture
- **Input**: Grayscale image (L channel in LAB color space)
- **Output**: Color channels (a,b channels in LAB color space)
- **Architecture**: U-Net with ResNet backbone
- **Loss Function**: MSE with optional perceptual loss

### Data Pipeline
1. **Preprocessing**: Images resized to 256×256
2. **Color Space**: RGB → LAB conversion
3. **Normalization**: Values scaled to [-1, 1]
4. **Augmentation**: Random flips, rotations, color jittering

## 📖 Documentation

### Training Your Own Model
```bash
# Prepare your dataset
python src/preprocessing/preprocess_dataset.py \
  --input_dir data/raw \
  --output_dir data/processed

# Start training
python src/train.py --config config/train_config.yaml

# Monitor with Weights & Biases (optional)
# Set wandb.enabled: true in config file
```

### Configuration
Edit `config/train_config.yaml` to customize:
- Model architecture (U-Net, CNN)
- Training parameters (learning rate, batch size)
- Data paths and preprocessing options
- Logging and checkpointing settings

### Using Makefile
```bash
make help          # Show available commands
make setup         # Setup project
make data          # Download sample data
make train         # Train model
make demo          # Run Streamlit demo
make api           # Start API server
make docker        # Build and run Docker
make test          # Run tests
```

## 🎨 Example Results

<div align="center">

| Input (Grayscale) | Output (Colorized) | Ground Truth |
|:-----------------:|:------------------:|:------------:|
| ![Grayscale](https://via.placeholder.com/200x200/808080/FFFFFF?text=Grayscale) | ![Colorized](https://via.placeholder.com/200x200/FF6B6B/FFFFFF?text=AI+Colorized) | ![Original](https://via.placeholder.com/200x200/4ECDC4/FFFFFF?text=Original) |

*Sample colorization results showing the model's ability to predict realistic colors*

</div>

## 🚀 Advanced Features

### 🎯 Custom Training
- Support for custom datasets
- Transfer learning from pretrained models
- Multi-GPU training support
- Automatic mixed precision

### 🌐 Production Deployment
- FastAPI with async support
- Docker containerization
- Health checks and monitoring
- Batch processing capabilities

### 📊 Evaluation Tools
- Comprehensive metrics calculation
- Visual comparison tools
- Performance benchmarking
- Error analysis utilities

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Setup
```bash
# Install development dependencies
make dev-install

# Run tests
make test

# Format code
make format

# Run linting
make lint
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Colorful Image Colorization](https://arxiv.org/abs/1603.08511) - Original research paper
- [U-Net](https://arxiv.org/abs/1505.04597) - Architecture inspiration
- [PyTorch](https://pytorch.org/) - Deep learning framework
- [Streamlit](https://streamlit.io/) - Web app framework

## 📞 Support

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/canuzlas/image-colorization/issues)
- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/canuzlas/image-colorization/discussions)
- 📧 **Email**: canuzlass@gmail.com

---

<div align="center">

**⭐ Star this repository if you found it helpful!**

Made with ❤️ by [canuzlas](https://github.com/canuzlas)

</div>