README.md

---
title: Hough Transform & RANSAC Line Detection
emoji: 📐
colorFrom: blue
colorTo: purple
sdk: streamlit
sdk_version: 1.28.0
app_file: app.py
pinned: false
license: mit
---

# Hough Transform & RANSAC Line Detection

An interactive educational tool for understanding line detection in images using Hough Transform and RANSAC algorithms.

## 🎯 Learning Objectives

This interactive app helps students in graduate-level image analysis courses understand:

1. **Hough Transform**
   - How sinograms represent lines in parameter space
   - The relationship between image space and Hough space
   - How accumulator arrays detect lines through voting
   - Parameter sensitivity (theta resolution, rho resolution, threshold)

2. **RANSAC (Random Sample Consensus)**
   - How RANSAC robustly fits lines to noisy data
   - The role of key parameters: iterations, distance threshold, minimum inliers
   - Comparison with least-squares fitting
   - Robustness to outliers

## 🚀 Features

- **Interactive Parameter Exploration**: Adjust parameters in real-time to see their effects
- **Sinogram Visualization**: View the Hough space accumulator array
- **Side-by-Side Comparisons**: Compare different parameter settings
- **Example Images**: Test with various edge-detected images
- **Educational Annotations**: Clear explanations of what's happening at each step

## 🛠️ How to Use

1. **Select an example image** or upload your own
2. **Adjust edge detection** parameters to extract features
3. **Explore Hough Transform** parameters and view the sinogram
4. **Compare with RANSAC** to see different line fitting approaches
5. **Experiment** with different parameter combinations to build intuition

## 📚 Background

### Hough Transform

The Hough Transform converts the problem of line detection from image space to parameter space. Each point in the image votes for all possible lines that could pass through it, creating an accumulator array (sinogram) where peaks correspond to detected lines.

### RANSAC

RANSAC is a robust estimation method that iteratively:
1. Samples minimum points needed to fit a model
2. Counts inliers (points that fit the model within a threshold)
3. Keeps the best model across iterations

## 🎓 Course Context

This tool is designed for graduate students in Introduction to Image Analysis courses, complementing lecture material on feature detection and robust estimation.

## 📖 References

- Duda, R. O. and P. E. Hart, "Use of the Hough Transformation to Detect Lines and Curves in Pictures," Comm. ACM, Vol. 15, pp. 11–15 (January, 1972)
- Fischler, M. A. and Bolles, R. C. (1981), "Random Sample Consensus: A Paradigm for Model Fitting with Applications to Image Analysis and Automated Cartography", Comm. of the ACM 24: 381–395

## 🔧 Local Development

### Quick Setup

```bash
# Option 1: Quick start (recommended)
./setup.sh
./run_simple.sh

# Option 2: Using Make
make setup
make run

# Option 3: Manual setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
streamlit run app.py
```

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

### Using uv (Fast Package Manager)

For faster dependency installation, install [uv](https://github.com/astral-sh/uv):

```bash
pip install uv
./setup.sh  # Will automatically use uv if available
```

## 🚀 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/new-space)
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
```

### Docker Deployment

You can also run the app using Docker:

```bash
# Build the image
docker build -t line-detection .

# Run the container
docker run -p 8501:8501 line-detection

# Access at http://localhost:8501
```

## 📁 Project Structure

```
line-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
├── pyproject.toml         # Project metadata (uv support)
├── Dockerfile             # Docker deployment
├── Makefile               # Convenient make commands
├── LICENSE                # MIT License
│
└── Scripts:
    ├── setup.sh           # Initial setup with venv/uv
    ├── run_simple.sh      # Quick local run
    ├── deploy.sh          # Deploy to HuggingFace
    └── check_status.sh    # Check deployment status
```

## 📝 License

MIT License - Feel free to use for educational purposes!