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