GETTING_STARTED.md

🎯 Getting Started with Colorspace Explorer

What You Have

A complete, production-ready Streamlit application for exploring colorspaces! This includes:

✅ Full application with 7 comprehensive tabs covering:

• RGB (additive color model)
• HSV/HSI (perceptual color)
• CIE-LAB (perceptually uniform)
• CMYK (subtractive/printing)
• YCbCr (compression-oriented)
• Gamma Correction & White Balance
• Color Blindness Simulation

✅ Complete deployment setup:

• Makefile for easy commands
• Deployment scripts for HuggingFace Spaces
• All configuration files

✅ Comprehensive documentation:

• README with full details
• QUICKSTART guide
• CONTRIBUTING guidelines
• PROJECT_SUMMARY

🚀 Next Steps

1. Test Locally (Recommended First!)

# Navigate to the project
cd /Users/amithkamath/Repositories/Teach/colorspaces

# Set up the environment (this will take a few minutes)
make setup

# Run the application
make run

The app will open in your browser at http://localhost:8501

2. Explore the Features

Try each tab:

1. RGB - Mix colors and see channel separation
2. HSV - Shift hues and adjust saturation
3. LAB - Explore perceptual color spaces
4. CMYK - See print separations
5. YCbCr - Test chroma subsampling
6. Gamma & WB - Correct brightness and color temperature
7. Color Blindness - Test accessibility with the numbered test images

3. Deploy to HuggingFace Spaces (Optional)

Once you're happy with the local version:

# Make sure you're logged in to HuggingFace
pip install huggingface-hub
huggingface-cli login

# Deploy
make deploy

Follow the prompts to enter your Space name (e.g., amithjkamath/colorspaces)

4. Customize (Optional)

You can easily customize the app:

Add your own images:

• Place images in the images/ folder
• Supported formats: PNG, JPG
• They'll automatically appear in the image selectors

Modify the content:

• Edit app.py to change functionality
• Update educational text in the markdown sections
• Adjust sliders, ranges, and default values

Add new colorspaces:

• See CONTRIBUTING.md for a template
• Follow the existing tab structure
• Add to the tabs list in main()

📋 Command Reference

make help      # Show all available commands
make setup     # One-time setup of environment
make run       # Start the app locally
make test      # Verify everything works
make clean     # Remove virtual environment
make deploy    # Deploy to HuggingFace Spaces
make status    # Check deployment status

🎓 Using in Class

For Live Demonstrations

1. Run locally with make run
2. Share your screen during lectures
3. Let students suggest parameter values to try
4. Use with projector for in-person classes

For Student Assignments

• Direct students to the deployed HuggingFace Space
• Or have them clone and run locally
• Assign exercises exploring different colorspaces
• Ask them to test their own images

For Homework

Example assignments:

• "Analyze how gamma correction affects dark vs bright images"
• "Compare 4:4:4 vs 4:2:0 subsampling on different types of images"
• "Test a design for colorblind accessibility"
• "Explain why HSV is better than RGB for color-based segmentation"

🔧 Troubleshooting

Issue: make: command not found

Solution: Install make or use manual commands:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

Issue: OpenCV import error

Solution: Make sure you're in the virtual environment:

source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate  # On Windows
pip install -r requirements.txt

Issue: Port already in use

Solution: Streamlit will automatically try the next port (8502, 8503, etc.)

Issue: Images not loading

Solution: Make sure you're running from the project directory and images/ folder exists

📊 Project Statistics

• Lines of Code: ~950+ in main app
• Colorspaces: 7 major colorspaces covered
• Tabs: 7 interactive tabs
• Educational Content: Comprehensive explanations and insights
• Dependencies: 5 core Python packages
• Sample Images: 15+ test images included

🎨 Demo Workflow

Here's a suggested order for demonstrating the app:

1. Start with RGB - Show basics of additive color
2. Move to HSV - Demonstrate perceptual intuition
3. Show LAB - Explain perceptual uniformity
4. Compare with CMYK - Contrast additive vs subtractive
5. Explore YCbCr - Show compression technique
6. Demonstrate Gamma - Explain display correction
7. Test White Balance - Show color temperature
8. Finish with Accessibility - Emphasize inclusive design

📚 Additional Resources

The app includes links to:

• Wikipedia articles on each colorspace
• Color science references
• Compression standards
• Accessibility guidelines

✅ Verification Checklist

Before your first class/demonstration:

• Tested locally with make run
• Explored all 7 tabs
• Uploaded a custom image to test
• Read through the educational content
• Checked colorblind test images (numbered files)
• Reviewed key insights sections
• Tested all sliders and controls
• Verified performance with sample images

🎉 You're Ready!

The application is complete and ready to use. Whether for:

• Interactive lectures
• Student exploration
• Homework assignments
• Research demonstrations

Everything you need is set up and documented.

📞 Need Help?

• Check PROJECT_SUMMARY.md for technical details
• See CONTRIBUTING.md for customization guidance
• Read README.md for comprehensive documentation
• Open issues on GitHub for bugs or questions

---

Happy teaching and exploring colorspaces! 🎨📚