IMAGES.md

# Sample Images Guide

The colorspace demo can work with any image, but here are some recommendations for educational purposes.

## Available Sample Images

The `images/` folder includes:

### Colorblind Test Plates
- **1-light.png** - Ishihara plate 1 (light version)
- **3-dark.png**, **3-light.png** - Ishihara plate 3
- **5-light.png** - Ishihara plate 5
- **6-light2.png** - Ishihara plate 6
- **7-med.png** - Ishihara plate 7
- **8-dark.png**, **8-light2.png** - Ishihara plate 8
- **9-dark.png**, **9-light.png** - Ishihara plate 9

These are standard test images for detecting color vision deficiency. Use them in the **Color Blindness** tab.

### Standard Test Images
- **cameraman.png** - Standard test image with varied tones and textures
- **lena.png** - Classic Lena test image (portrait)
- **checkerboard.png** - Regular geometric pattern for testing
- **circles.jpg** - Colored circles
- **shapes.jpg** - Various geometric shapes
- **various scene images** - People, objects, and natural scenes

## Using Your Own Images

### Option 1: Upload at Runtime (Recommended for Users)
The simplest way is to use the **file uploader** in each tab's sidebar. Users can upload their own images to experiment with.

**Supported formats:** PNG, JPG, JPEG

**Recommendations for testing:**
- **RGB Tab**: Use images with distinct colors (shapes.jpg, circles.jpg)
- **HSV Tab**: Try colorful images for hue shifting (circles.jpg)
- **LAB Tab**: Use images with smooth gradients to see perceptual differences
- **CMYK Tab**: Use photographs to see print separations (lena.png)
- **YCbCr Tab**: Use detailed images to see compression differences (cameraman.png)
- **Gamma Tab**: Use images with varying brightness (cameraman.png, lena.png)
- **White Balance Tab**: Use images with potential color casts
- **Color Blindness Tab**: Use the numbered test plates for verification

### Option 2: Bundle with Repository (Current Setup)

Images are included in the `images/` folder and automatically deployed with the application. This ensures users always have test images available.

To add more images:

1. **Save images to images/ folder:**
   ```bash
   cp your_image.png images/
   ```

2. **Supported formats:**
   - PNG (`.png`)
   - JPEG (`.jpg`, `.jpeg`)

3. **Git considerations:**
   - Images are tracked in git
   - For large images (>5MB), consider using git-lfs or a separate dataset
   - Keep images reasonably sized (< 1MB each for good performance)

### Option 3: Use HuggingFace Dataset (Optional Enhancement)

For even better scalability, you can use a HuggingFace dataset:

1. **Create a dataset on HuggingFace:**
   - Go to https://huggingface.co/new-dataset
   - Upload your images
   - Make it public

2. **Update `app.py` to download from dataset:**
   ```python
   from huggingface_hub import hf_hub_download
   
   image_path = hf_hub_download(
       repo_id="your-username/colorspace-images",
       filename="your-image.jpg",
       repo_type="dataset",
   )
   img = cv.imread(image_path)
   ```

## Best Practices for Educational Images

### For Different Colorspaces

**RGB Exploration:**
- Images with distinct primary colors
- Images with secondary colors (cyan, magenta, yellow)
- Black and white images

**HSV/HSI Exploration:**
- Colorful images with varied hues
- Images with different saturation levels
- Grayscale images to show zero saturation

**LAB Exploration:**
- Images with smooth color transitions
- Images with uniform regions (for color difference testing)
- Photographs with natural color variations

**CMYK (Print) Exploration:**
- Photographs (natural prints well)
- Images with varied colors
- Graphics with solid colors

**YCbCr (Compression) Exploration:**
- Detailed images with high-frequency content
- Natural photographs
- Images with fine textures

**Gamma Correction:**
- Images with a wide tonal range
- Images with bright and dark regions
- Portrait images

**White Balance:**
- Images with known color casts
- Images in different lighting conditions (if simulated)
- Portrait images

**Color Blindness:**
- The provided Ishihara test plates
- Colored graphs or visualizations
- Images meant to be accessible to all

## Image Specifications

### Recommended
- **Size**: 200-800 pixels on longest dimension
- **Format**: PNG for lossless, JPG for photos
- **File size**: < 1MB per image
- **Color depth**: RGB, 8-bit per channel

### Automatic Processing
The app automatically:
- Resizes large images to 400-600px for display
- Handles various image formats
- Displays images side-by-side for comparison
- Caches loaded images for performance

## Adding Images to Git

```bash
# Add a new image
cp image_file.png images/
git add images/image_file.png
git commit -m "Add new test image for colorspace exploration"
```

## Troubleshooting Images

**Image not appearing:**
- Check file is in `images/` folder
- Verify file format (PNG or JPG)
- Check file isn't corrupted: `file images/myimage.jpg`

**Image loading slowly:**
- Consider reducing image resolution
- Convert to JPG if it's very large
- Check available disk space

**Color looks different across tabs:**
- This is normal! Different colorspaces represent colors differently
- Use LAB for the most perceptually accurate representation

---

For more information, see the main [README.md](README.md).