README.md

metadata

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.

🌈 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

   git clone https://github.com/ubern-image-analysis/colorspaces.git
   cd colorspaces
   

2. Set up the environment

   make setup
   

3. Run the application

   make run
   

4. Open your browser

   • The app will automatically open at http://localhost:8501

Using Make Commands

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 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

2. Create a new Space:

   • Go to huggingface.co/spaces
   • Click "Create new Space"
   • Choose "Streamlit" as the SDK
   • Name it (e.g., colorspaces)

3. Install Hugging Face CLI and login:

   pip install huggingface-hub
   huggingface-cli login
   

Deploy

1. Initialize git (if not already done)

   git init
   git add .
   git commit -m "Initial commit"
   

2. Deploy to Hugging Face

   make deploy
   

   Follow the prompts and enter your Space name (e.g., username/colorspaces)

3. Check status

   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

# 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 file for details.

👥 Authors

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

🙏 Acknowledgments

• Based on the sampling-quantization demo
• Colorblind simulation algorithms from Brettel, Viénot, and Mollon
• Test images from standard image processing datasets

📧 Contact

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

---

Made with ❤️ and Streamlit