README.md

---
title: Interactive Edge Detection Demo
colorFrom: red
colorTo: yellow
sdk: streamlit
sdk_version: 1.39.0
app_file: app.py
pinned: false
license: mit
---

# 🔍 Interactive Edge Detection Demo

An educational demonstration of classical and advanced edge detection algorithms for graduate-level image analysis courses.

## What You'll Learn

This interactive demo explores the computational foundations of edge detection:

- **Classical Gradient-Based Methods**: Sobel, Prewitt, Roberts Cross operators
- **Second-Order Methods**: Laplacian edge detection
- **Optimal Edge Detection**: The Canny algorithm and its multi-stage pipeline
- **Comparative Analysis**: Understanding trade-offs between different approaches
- **Mathematical Foundations**: Gradients, derivatives, and convolution kernels
- **Practical Considerations**: Pre-processing, parameter tuning, and method selection

## Features

### Interactive Edge Detection
- **Five Detection Methods**: Sobel, Prewitt, Roberts, Laplacian, and Canny
- **Real-Time Visualization**: See edges detected as you adjust parameters
- **Gradient Analysis**: Visualize gradient components (Gx, Gy) and directions
- **Side-by-Side Comparison**: Compare any method with Canny edge detection

### Educational Content
- **Four Educational Tabs**: Comprehensive explanations of theory and practice
- **Mathematical Formulations**: Kernel definitions and gradient equations
- **"Aha!" Moments**: Key insights that make concepts click
- **Practical Guidance**: When to use each method and how to tune parameters

### Customization
- **Upload Your Images**: Test algorithms on your own data
- **Pre-processing Options**: Apply Gaussian blur to reduce noise
- **Method-Specific Parameters**: Kernel sizes, thresholds, and more
- **Gradient Visualizations**: Color-coded direction and magnitude maps

## Quick Start

### Online Usage
Visit the Hugging Face Space (URL provided by your instructor) to use the demo directly in your browser.

### Local Development

#### Setup

```bash
# Clone the repository
git clone <your-repo-url>
cd edge-detection

# Install dependencies
pip install -r requirements.txt
```

#### Run Locally

```bash
# Simple run
streamlit run app.py

# Or use the provided script
chmod +x run_simple.sh
./run_simple.sh
```

The app will be available at `http://localhost:8501`

## Deployment to Hugging Face Spaces

This app is designed to be deployed to Hugging Face Spaces:

1. Create a new Space on [Hugging Face](https://huggingface.co/spaces)
2. Choose "Streamlit" as the SDK
3. Push this repository to your Space

Or use the deployment script:

```bash
chmod +x deploy.sh
./deploy.sh
```

## Educational Use

This demo is designed for:
- Graduate image analysis courses
- Computer vision fundamentals
- Digital image processing tutorials
- Self-paced learning about edge detection

### Key Concepts Covered

- **Image Gradients**: First-order derivatives and directional information
- **Convolution Kernels**: How discrete filters approximate derivatives
- **Multi-Scale Analysis**: The role of smoothing in edge detection
- **Optimal Edge Detection**: Canny's three criteria and their implementation
- **Practical Trade-offs**: Speed vs. quality, simplicity vs. robustness

### Suggested Learning Path

1. **Start with Roberts**: Understand the basic concept of gradient operators
2. **Progress to Sobel/Prewitt**: See how larger kernels improve robustness
3. **Explore Laplacian**: Learn about second-order derivatives
4. **Master Canny**: Understand the multi-stage optimal approach
5. **Compare Methods**: Use the comparison feature to see differences

## Project Structure

```
edge-detection/
├── app.py                  # Main Streamlit application
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── packages.txt           # System dependencies for HF Spaces
├── .python-version        # Python version specification
├── Dockerfile             # Docker deployment
├── setup.sh               # Setup script
├── run_simple.sh          # Local run script
└── deploy.sh              # Deployment helper script
```

## Technical Details

### Implemented Algorithms

**Roberts Cross (1963)**
- 2×2 diagonal gradient kernels
- Fastest, simplest method
- Good for sharp, diagonal edges

**Prewitt (1970)**
- 3×3 gradient kernels with equal weighting
- Incorporates smoothing perpendicular to gradient
- Good balance of simplicity and robustness

**Sobel (1968)**
- 3×3 gradient kernels with center weighting
- Most widely used first-order operator
- Better approximation of true gradient

**Laplacian**
- Second-order isotropic operator
- Detects zero-crossings
- Requires careful noise handling

**Canny (1986)**
- Five-stage optimal edge detector
- Combines smoothing, gradients, NMS, and hysteresis
- Industry standard for quality edge detection

## License

MIT License - Free for educational and commercial use

## Credits

Created for the Intro to Image Analysis course at the University of Bern.
Inspired by interactive teaching tools for computer vision education.

## References

- Canny, J. (1986). "A Computational Approach to Edge Detection." IEEE TPAMI.
- Gonzalez & Woods. "Digital Image Processing" (4th Edition).
- Szeliski, R. "Computer Vision: Algorithms and Applications."