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:

   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:

   mkdir sample_images
   

2. Add images to .gitignore if they're large:

   sample_images/*.jpg
   sample_images/*.png
   

3. Update app.py:

   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:

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.