IMAGES.md

# Sample Images Guide

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

## Using Your Own Images

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

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

**Recommendations:**
- Images with gradients (to show posterization)
- Images with fine details (to show pixelation)
- Images with sharp edges (to show JPEG artifacts)
- Natural photos vs. graphics/screenshots

### Option 2: Use HuggingFace Dataset (Recommended for Deployment)

If you want a default image always available, 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`:**
   ```python
   image_path = hf_hub_download(
       repo_id="your-username/your-dataset-name",
       filename="your-image.jpg",
       repo_type="dataset",
   )
   ```

### Option 3: Bundle with Repository

For local development, you can include images in the repository:

1. **Create a directory:**
   ```bash
   mkdir sample_images
   ```

2. **Add images to `.gitignore` if they're large:**
   ```
   sample_images/*.jpg
   sample_images/*.png
   ```

3. **Update `app.py`:**
   ```python
   img = cv.imread('sample_images/your-image.jpg')
   img = cv.cvtColor(img, cv.COLOR_BGR2RGB)
   ```

## Recommended Image Types

### For Demonstrating Sampling (Pixelation)

**Good choices:**
- **Text documents or signs** - shows when text becomes unreadable
- **Portraits** - shows loss of facial detail
- **Architectural photos** - shows loss of fine lines and edges
- **Natural scenes** - shows overall degradation

**Characteristics:**
- High resolution (512x512 or larger)
- Clear details at different scales
- Mix of fine and coarse features

### For Demonstrating Quantization (Bit Depth)

**Good choices:**
- **Sunset/sunrise photos** - smooth color gradients
- **Blue sky** - shows banding clearly
- **Gradients** - artificial gradients work great
- **Portraits** - shows posterization in skin tones

**Characteristics:**
- Smooth color transitions
- Wide tonal range
- Subtle color variations

### For Demonstrating JPEG Artifacts

**Good choices:**
- **Graphics with solid colors** - shows blocking clearly
- **Screenshots with text** - compression artifacts around text
- **High-contrast edges** - ringing artifacts
- **Patterns** - mosquito noise

**Characteristics:**
- Sharp edges
- Solid color areas
- High contrast regions
- Fine patterns or textures

## Sample Image Sources

### Free Stock Photos (Educational Use)
- **Unsplash**: https://unsplash.com/ (free license)
- **Pexels**: https://www.pexels.com/ (free license)
- **Pixabay**: https://pixabay.com/ (free license)

### Scientific Image Datasets
- **USC-SIPI Image Database**: http://sipi.usc.edu/database/
  - Standard test images used in image processing research
  - Includes "Lena", "Peppers", "Airplane", etc.
  
- **ImageNet**: https://image-net.org/
  - Massive dataset, but you only need a few samples

### Creating Your Own Test Images

Use Python to generate test images with specific properties:

```python
import numpy as np
import cv2 as cv

# Gradient image (good for quantization demo)
gradient = np.zeros((512, 512, 3), dtype=np.uint8)
for i in range(512):
    gradient[i, :, :] = int(255 * i / 512)
cv.imwrite('gradient.png', gradient)

# Pattern image (good for JPEG artifacts demo)
pattern = np.zeros((512, 512, 3), dtype=np.uint8)
pattern[::8, :] = 255  # Horizontal lines
pattern[:, ::8] = 255  # Vertical lines
cv.imwrite('pattern.png', pattern)

# Noise image (good for compression comparison)
noise = np.random.randint(0, 256, (512, 512, 3), dtype=np.uint8)
cv.imwrite('noise.png', noise)
```

## Image Guidelines

For best educational results:

1. **Size**: 512x512 or similar (not too large, loads faster)
2. **Format**: PNG for original (lossless)
3. **Content**: Clear subject matter, recognizable features
4. **Variety**: Have different types available for different concepts
5. **Rights**: Ensure you have permission to use/distribute

## Current Implementation

The app currently:
1. **Tries to download** from HuggingFace (if configured)
2. **Falls back** to a generated sample image with:
   - Color gradients
   - Geometric shapes
   - Text
3. **Allows upload** via sidebar

This ensures the demo works even without internet access or external dependencies.

## Testing Your Images

Before using an image in production, test:
- Does it load quickly?
- Are effects visible at different sampling rates?
- Does quantization create noticeable banding?
- Are JPEG artifacts visible at low quality?
- Is the file size reasonable (<5MB)?

## Need Help?

For questions about image preparation or integration, open an issue on GitHub.