| # Image Sampling and Quantization Demo - Project Summary |
|
|
| ## Overview |
|
|
| This interactive educational demo teaches fundamental concepts in digital image processing: |
| - **Spatial Sampling**: How resolution affects image quality and storage |
| - **Quantization**: How bit depth impacts color representation |
| - **Compression**: Differences between PNG (lossless) and JPEG (lossy) |
|
|
| ## Key Features |
|
|
| ### Interactive Controls |
| - **Sampling Grid Size Slider** (1-16x): Shows pixelation effect and pixel count reduction |
| - **Bits per Pixel Slider** (1-8 bits): Demonstrates color depth and posterization |
| - **JPEG Quality Slider** (1-100): Shows compression artifacts |
|
|
| ### Real-Time Feedback |
| - **Live File Size Estimates**: Shows how settings affect storage requirements |
| - **Side-by-Side Comparisons**: Original vs. processed images |
| - **Detailed Calculations**: Transparent math showing how sizes are computed |
|
|
| ### Educational Content |
| - **Three Educational Tabs**: Dedicated sections for Sampling, Quantization, and Compression |
| - **Visual Examples**: All concepts demonstrated with live image processing |
| - **Formula Explanations**: Mathematical basis for all calculations |
|
|
| ## Educational Objectives |
|
|
| Students will learn: |
| 1. The relationship between sampling rate and image resolution |
| 2. How quantization affects color depth and file size |
| 3. The trade-offs between image quality and storage |
| 4. Differences between lossy and lossless compression |
| 5. How JPEG blocking artifacts occur |
|
|
| ## Project Structure |
|
|
| ``` |
| sampling-quantization/ |
| ├── app.py # Main Streamlit application (500+ lines) |
| ├── requirements.txt # Python dependencies |
| ├── README.md # Main documentation |
| ├── QUICKSTART.md # Getting started guide |
| ├── CONTRIBUTING.md # Contribution guidelines |
| ├── IMAGES.md # Guide for sample images |
| ├── LICENSE # MIT License |
| │ |
| ├── Configuration Files: |
| ├── packages.txt # System dependencies for HF Spaces |
| ├── .python-version # Python 3.11 |
| ├── .gitignore # Git ignore rules |
| ├── pyproject.toml # Project metadata |
| ├── Dockerfile # Docker deployment |
| ├── Makefile # Convenient make commands |
| │ |
| └── Scripts: |
| ├── setup.sh # Initial setup with venv |
| ├── run_simple.sh # Quick local run |
| ├── deploy.sh # Deploy to HuggingFace |
| └── check_status.sh # Check deployment status |
| ``` |
|
|
| ## Quick Start |
|
|
| ### For Users (Simplest) |
| ```bash |
| chmod +x run_simple.sh |
| ./run_simple.sh |
| ``` |
|
|
| ### Using Make |
| ```bash |
| make setup # First time only |
| make run # Start the app |
| ``` |
|
|
| ### Manual Setup |
| ```bash |
| python3 -m venv venv |
| source venv/bin/activate |
| pip install -r requirements.txt |
| streamlit run app.py |
| ``` |
|
|
| ## Deployment Options |
|
|
| ### 1. Hugging Face Spaces (Recommended) |
| ```bash |
| ./deploy.sh |
| ``` |
| - Free hosting |
| - Automatic builds |
| - Share with students via URL |
| - No server maintenance |
|
|
| ### 2. Docker |
| ```bash |
| docker build -t sampling-demo . |
| docker run -p 8501:8501 sampling-demo |
| ``` |
|
|
| ### 3. Local Server |
| ```bash |
| streamlit run app.py --server.port 8501 |
| ``` |
|
|
| ## Teaching with This Demo |
|
|
| ### Suggested Lesson Plan |
|
|
| **Part 1: Sampling (15 minutes)** |
| 1. Start with original image at 1x sampling, 8 bits |
| 2. Gradually increase sampling rate (2x, 4x, 8x, 16x) |
| 3. Discuss: When does text become unreadable? |
| 4. Calculate storage savings |
|
|
| **Part 2: Quantization (15 minutes)** |
| 1. Reset sampling to 1x |
| 2. Reduce bits per pixel (8 to 4 to 2 to 1) |
| 3. Discuss: Color banding, posterization |
| 4. Show grayscale interpretation |
|
|
| **Part 3: Compression (20 minutes)** |
| 1. Apply moderate sampling/quantization |
| 2. Compare PNG vs JPEG at different qualities |
| 3. At JPEG quality < 30: Point out 8x8 blocking |
| 4. Discuss use cases for each format |
|
|
| **Part 4: Interactive Exploration (10 minutes)** |
| 1. Let students experiment with their own images |
| 2. Find optimal settings for different use cases |
| 3. Calculate real-world storage requirements |
|
|
| ### Discussion Questions |
|
|
| 1. What is the minimum acceptable sampling rate for your use case? |
| 2. How many bits per pixel do you really need for grayscale medical images? |
| 3. When would you choose PNG over JPEG and vice versa? |
| 4. Why do JPEG artifacts appear in 8x8 blocks? |
| 5. What's the total storage for 1000 photos at different settings? |
|
|
| ## Technical Details |
|
|
| ### Image Processing Pipeline |
| ``` |
| Original Image |
| ↓ |
| Spatial Sampling (downsample to upsample with nearest neighbor) |
| ↓ |
| Quantization (reduce bits per channel) |
| ↓ |
| Compression (PNG lossless or JPEG lossy) |
| ↓ |
| Display + File Size Calculation |
| ``` |
|
|
| ### File Size Calculation |
| ``` |
| Raw Size = (Width / Sampling) x (Height / Sampling) x Channels x Bits / 8 |
| |
| PNG Size ≈ Raw Size x 0.7 (typical compression ratio) |
| JPEG Size ≈ Raw Size x 0.3 (typical compression ratio) |
| ``` |
|
|
| ### Key Algorithms |
| - **Downsampling**: `cv.INTER_AREA` (best quality for reduction) |
| - **Upsampling**: `cv.INTER_NEAREST` (shows pixelation clearly) |
| - **Quantization**: `floor(value / step) * step` where `step = 256 / 2^bits` |
| - **JPEG**: OpenCV's `cv.imencode()` with quality parameter |
|
|
| ## Customization |
|
|
| ### Change Default Image |
| Edit `load_sample_image()` in `app.py`: |
| ```python |
| image_path = hf_hub_download( |
| repo_id="your-username/your-dataset", |
| filename="your-image.jpg", |
| repo_type="dataset", |
| ) |
| ``` |
|
|
| ### Adjust Slider Ranges |
| In `app.py`, modify slider parameters: |
| ```python |
| sampling_rate = st.sidebar.slider( |
| "Sampling Grid Size (pixels)", |
| min_value=1, # Change these |
| max_value=32, # Change these |
| value=1, |
| ) |
| ``` |
|
|
| ### Add New Features |
| See `CONTRIBUTING.md` for guidelines on adding: |
| - New compression algorithms |
| - Additional image metrics |
| - Interactive exercises |
| - Batch processing |
|
|
| ## Performance |
|
|
| - **Load Time**: < 2 seconds on first load (with caching) |
| - **Interactive Response**: Real-time (< 100ms per slider change) |
| - **Memory Usage**: ~200-300 MB (depends on image size) |
| - **Supported Image Sizes**: Up to 4K (auto-resized to 512px for demo) |
|
|
| ## Known Limitations |
|
|
| 1. Very large images (>10MB) may be slow - auto-resized to 512px |
| 2. JPEG artifact visibility depends on image content |
| 3. File size estimates are approximate (actual compression varies) |
| 4. Generated sample image is simple (encourage uploading real images) |
|
|
| ## Educational Resources |
|
|
| Concepts covered align with: |
| - Digital Image Processing (Gonzalez & Woods) |
| - Computer Vision fundamentals courses |
| - Signal processing curricula |
| - Compression theory courses |
|
|
| ## Contributing |
|
|
| We welcome contributions! See `CONTRIBUTING.md` for: |
| - Bug reports |
| - Feature requests |
| - Code contributions |
| - Documentation improvements |
| - Educational content enhancements |
|
|
| ## License |
|
|
| MIT License - Free for educational and commercial use |
|
|
| ## Acknowledgments |
|
|
| - Inspired by interactive teaching tools in computer vision |
| - Built with Streamlit for rapid prototyping |
| - OpenCV for image processing |
| - HuggingFace for free hosting |
|
|
| ## Support |
|
|
| - **Issues**: GitHub Issues for bugs and features |
| - **Questions**: Discussion board for educational questions |
| - **Documentation**: See README.md, QUICKSTART.md, IMAGES.md |
|
|
| ## Success Stories |
|
|
| Perfect for: |
| - Graduate image analysis courses |
| - Computer vision fundamentals |
| - Self-paced online learning |
| - Workshop demonstrations |
| - Research group tutorials |
|
|
| --- **Ready to start?** Run `./run_simple.sh` and explore! |
|
|
