Hugging Face's logo

Spaces:
ubern-introimage
/
sampling-quantization
Sleeping

App Files Community
sampling-quantization / PROJECT_SUMMARY.md
AKA Math
Remove emojis and symbols from all files, update Dockerfile
d962d48
preview code
|
Raw
History Blame Contribute Delete
7.44 kB

A newer version of the Streamlit SDK is available: 1.62.0

Upgrade

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) 

chmod +x run_simple.sh
./run_simple.sh

Using Make 

make setup    # First time only
make run      # Start the app

Manual Setup 

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

Deployment Options

1. Hugging Face Spaces (Recommended) 

./deploy.sh
  • Free hosting
  • Automatic builds
  • Share with students via URL
  • No server maintenance

2. Docker 

docker build -t sampling-demo .
docker run -p 8501:8501 sampling-demo

3. Local Server 

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:

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:

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!