# 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:**
   ```bash
   git clone <repository-url>
   cd sampling-quantization
   ```

2. **Run the setup script:**
   ```bash
   chmod +x setup.sh
   ./setup.sh
   ```

3. **Start the demo:**
   ```bash
   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:

```python
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:**
   ```bash
   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](https://docs.streamlit.io/)
- [OpenCV Python Tutorials](https://docs.opencv.org/master/d6/d00/tutorial_py_root.html)
- [Digital Image Processing Fundamentals](https://en.wikipedia.org/wiki/Digital_image_processing)