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:**
   ```bash
   git clone <repository-url>
   cd edge-detection
   ```

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
- `apply_sobel_filter()`, `apply_prewitt_filter()`, etc.: Modify filter implementations
- `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., "edge-detection-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/edge-detection-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 Roberts Cross to introduce the gradient concept
2. **Progress Gradually**: Move to Sobel/Prewitt, then Laplacian
3. **Culminate with Canny**: Show how optimal edge detection builds on simpler methods
4. **Use Comparisons**: Enable side-by-side comparisons to highlight differences

### Discussion Points

- **Gradient Operators**: Why do we need 2D convolution kernels?
- **First vs. Second Order**: When is Laplacian better than Sobel?
- **Canny's Criteria**: What makes an edge detector "optimal"?
- **Trade-offs**: Speed vs. quality, simplicity vs. robustness

### Suggested Exercises

1. Compare edge detection on images with different noise levels
2. Find optimal Canny thresholds for different types of images
3. Analyze how kernel size affects edge localization
4. Examine gradient direction patterns in natural images
5. Compare computational complexity of different methods

## Resources

- [OpenCV Edge Detection Tutorial](https://docs.opencv.org/master/da/d22/tutorial_py_canny.html)
- [Canny's Original Paper (1986)](https://ieeexplore.ieee.org/document/4767851)
- [Digital Image Processing (Gonzalez & Woods)](http://www.imageprocessingplace.com/)
- [Computer Vision: Algorithms and Applications (Szeliski)](http://szeliski.org/Book/)