README.md

---
title: Interactive Colorspace Exploration
emoji: 🎨
colorFrom: purple
colorTo: pink
sdk: streamlit
sdk_version: "1.39.0"
python_version: "3.9"
app_file: app.py
pinned: false
---

# 🎨 Interactive Colorspace Exploration

An educational Streamlit application for exploring different colorspaces and color models used in image processing and computer vision. Built for graduate-level image analysis courses.

[![Open in Streamlit](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://huggingface.co/spaces/YOUR_USERNAME/colorspaces)

## 🌈 Features

This interactive demo covers the following topics:

### 📚 Colorspaces Covered

1. **RGB (Red, Green, Blue)**
   - Additive color model
   - Channel visualization and manipulation
   - Primary and secondary colors
   - Device-dependent representation

2. **HSV/HSI (Hue, Saturation, Value/Intensity)**
   - Cylindrical color representation
   - Perceptually intuitive controls
   - Color, saturation, and brightness separation
   - Interactive hue shifting and saturation adjustment

3. **CIE-LAB**
   - Perceptually uniform colorspace
   - Device-independent
   - Color difference calculations (ΔE)
   - Lightness and opponent color channels

4. **CMYK (Cyan, Magenta, Yellow, Key/Black)**
   - Subtractive color model
   - Printing and print separation
   - Comparison with additive (RGB) model
   - Understanding ink absorption

5. **YCbCr (Luma, Blue-difference, Red-difference)**
   - Compression-oriented colorspace
   - Chroma subsampling (4:4:4, 4:2:2, 4:2:0)
   - JPEG and video compression applications
   - Luminance-chrominance separation

6. **Gamma Correction**
   - Non-linear display response compensation
   - Gamma curves and their effects
   - Histogram visualization
   - Standard gamma values (sRGB, Rec. 709)

7. **White Balance**
   - Color temperature correction
   - Different lighting conditions (daylight, incandescent, fluorescent)
   - Gray world assumption
   - Manual and automatic white balance

8. **Color Blindness Simulation**
   - Protanopia (no red cones)
   - Deuteranopia (no green cones)
   - Tritanopia (no blue cones)
   - Monochromacy (no color vision)
   - Accessibility guidelines
   - Ishihara test images

## 🚀 Quick Start

### Local Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/ubern-image-analysis/colorspaces.git
   cd colorspaces
   ```

2. **Set up the environment**
   ```bash
   make setup
   ```

3. **Run the application**
   ```bash
   make run
   ```

4. **Open your browser**
   - The app will automatically open at `http://localhost:8501`

### Using Make Commands

```bash
make help      # Show all available commands
make setup     # Set up virtual environment and install dependencies
make run       # Run the Streamlit app locally
make clean     # Remove virtual environment and cache files
make test      # Run basic tests
make deploy    # Deploy to Hugging Face Spaces
make status    # Check deployment status
```

## 📦 Requirements

- Python 3.8 or higher
- See [requirements.txt](requirements.txt) for package dependencies:
  - streamlit
  - numpy
  - opencv-python
  - pillow
  - matplotlib

## 🖼️ Images

The demo includes various test images in the `images/` folder:
- Ishihara colorblind test plates (numbered images)
- Standard test images (cameraman, Lena, etc.)
- Geometric shapes and patterns
- Natural scenes with people and objects

You can also upload your own images to explore different colorspaces!

## 🎓 Educational Goals

This tool is designed to help students:

1. **Understand color representation** in different colorspaces
2. **Visualize color transformations** between spaces
3. **Explore perceptual properties** of different models
4. **Learn compression techniques** like chroma subsampling
5. **Practice color correction** with gamma and white balance
6. **Design for accessibility** using colorblind simulations

## 🌐 Deployment to Hugging Face Spaces

### Prerequisites

1. Create a Hugging Face account at [huggingface.co](https://huggingface.co)
2. Create a new Space:
   - Go to [huggingface.co/spaces](https://huggingface.co/spaces)
   - Click "Create new Space"
   - Choose "Streamlit" as the SDK
   - Name it (e.g., `colorspaces`)

3. Install Hugging Face CLI and login:
   ```bash
   pip install huggingface-hub
   huggingface-cli login
   ```

### Deploy

1. **Initialize git (if not already done)**
   ```bash
   git init
   git add .
   git commit -m "Initial commit"
   ```

2. **Deploy to Hugging Face**
   ```bash
   make deploy
   ```
   
   Follow the prompts and enter your Space name (e.g., `username/colorspaces`)

3. **Check status**
   ```bash
   make status
   ```

Your Space will be live at `https://huggingface.co/spaces/YOUR_USERNAME/colorspaces`!

## 📖 Usage Tips

### For Students
- Start with the RGB tab to understand the basics
- Progress through HSV to see perceptual color representation
- Explore LAB for color difference calculations
- Compare RGB (additive) with CMYK (subtractive)
- Learn about compression with YCbCr
- Experiment with gamma correction and white balance
- Test your designs for colorblind accessibility

### For Instructors
- Use this alongside lecture materials on color theory
- Demonstrate concepts interactively in class
- Assign exercises using different colorspaces
- Have students test their designs for accessibility
- Compare compression artifacts in YCbCr

## 🔧 Development

### Project Structure
```
colorspaces/
├── app.py              # Main Streamlit application
├── requirements.txt    # Python dependencies
├── Makefile           # Build and deployment commands
├── deploy.sh          # Deployment script for HuggingFace
├── check_status.sh    # Status checking script
├── README.md          # This file
├── LICENSE            # License file
└── images/            # Sample images
    ├── 1-light.png    # Colorblind test images
    ├── cameraman.png  # Standard test images
    └── ...
```

### Adding New Features

1. Create a new tab function in `app.py`
2. Add educational content with markdown
3. Include interactive controls (sliders, buttons)
4. Visualize results with side-by-side comparisons
5. Add explanatory text and key insights

### Testing Locally

```bash
# Run tests
make test

# Start the app
make run

# Clean up
make clean
```

## 📚 References

### Color Science
- CIE 1931 color space: https://en.wikipedia.org/wiki/CIE_1931_color_space
- sRGB specification: https://en.wikipedia.org/wiki/SRGB
- Color difference (ΔE): https://en.wikipedia.org/wiki/Color_difference

### Colorspaces
- RGB: https://en.wikipedia.org/wiki/RGB_color_model
- HSV: https://en.wikipedia.org/wiki/HSL_and_HSV
- LAB: https://en.wikipedia.org/wiki/CIELAB_color_space
- CMYK: https://en.wikipedia.org/wiki/CMYK_color_model
- YCbCr: https://en.wikipedia.org/wiki/YCbCr

### Compression
- Chroma subsampling: https://en.wikipedia.org/wiki/Chroma_subsampling
- JPEG: https://en.wikipedia.org/wiki/JPEG

### Accessibility
- Color blindness: https://en.wikipedia.org/wiki/Color_blindness
- Ishihara test: https://en.wikipedia.org/wiki/Ishihara_test
- Web accessibility: https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html

## 🤝 Contributing

Contributions are welcome! Please feel free to:
- Report bugs
- Suggest new features
- Add more colorspaces or demonstrations
- Improve documentation
- Add more test images

## 📄 License

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

## 👥 Authors

Created for graduate-level image analysis courses at the University of Bern.

## 🙏 Acknowledgments

- Based on the [sampling-quantization demo](https://github.com/ubern-image-analysis/sampling-quantization)
- Colorblind simulation algorithms from [Brettel, Viénot, and Mollon](http://www.daltonize.org/)
- Test images from standard image processing datasets

## 📧 Contact

For questions or feedback, please open an issue on GitHub.

---

Made with ❤️ and [Streamlit](https://streamlit.io)