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