QUICKSTART.md

Quick Start Guide

For Students/Users

Online Usage

Simply visit the Hugging Face Space URL (provided by your instructor) to use the demo directly in your browser. No installation needed!

Local Usage

1. Clone the repository:

   git clone <repository-url>
   cd sampling-quantization
   

2. Run the setup script:

   chmod +x setup.sh
   ./setup.sh
   

3. Start the demo:

   chmod +x run_simple.sh
   ./run_simple.sh
   

4. Open your browser to http://localhost:8501

For Instructors/Developers

Customizing the Demo

The main application is in app.py. Key functions you can modify:

• generate_sample_image(): Customize the default sample image
• downsample_image(): Adjust the sampling algorithm
• quantize_image(): Modify quantization behavior
• main_loop(): Change the UI layout and educational content

Using Your Own Images

You have two options:

1. Upload at runtime: Users can upload images via the sidebar
2. Default image: Modify the load_sample_image() function to load from a URL or local path

To use images from your own HuggingFace dataset:

image_path = hf_hub_download(
    repo_id="your-username/your-dataset",
    filename="your-image.jpg",
    repo_type="dataset",
)

Deploying to Hugging Face Spaces

1. Create a Space:

   • Go to https://huggingface.co/new-space
   • Choose a name (e.g., "sampling-quantization-demo")
   • Select "Streamlit" as the SDK
   • Choose "Public" for educational use

2. Deploy:

   chmod +x deploy.sh
   ./deploy.sh
   

3. Enter your Space name when prompted (e.g., "username/sampling-quantization-demo")

Troubleshooting

"Import errors" when running locally:

• Make sure you ran setup.sh first
• Activate the virtual environment: source venv/bin/activate
• Reinstall requirements: pip install -r requirements.txt

App not loading on HuggingFace:

• Check the "Logs" tab in your Space
• Verify packages.txt includes all system dependencies
• Ensure Python version in .python-version is supported

Images not displaying:

• Check if the HuggingFace dataset is public
• Verify the repo_id and filename in load_sample_image()
• The app will fall back to a generated image if download fails

Educational Tips

For Teaching

1. Start Simple: Begin with just sampling (set quantization to 8 bits)
2. Progress Gradually: Then introduce quantization concepts
3. Compare Methods: Finally explore compression algorithms

Discussion Points

• Sampling: Nyquist theorem, aliasing, pixelation
• Quantization: Posterization, banding, perceptual quality
• Compression: Lossy vs lossless, artifacts, use cases

Assignments

Suggested exercises:

1. Find the minimum sampling rate before text becomes unreadable
2. Determine the minimum bits per pixel for acceptable quality
3. Compare JPEG and PNG for different image types
4. Calculate storage requirements for different image sizes

Resources

• Streamlit Documentation
• OpenCV Python Tutorials
• Digital Image Processing Fundamentals