GETTING_STARTED.md

# 📖 Getting Started with the Edge Detection Demo

## Prerequisites

- **Python 3.11+** (Python 3.9+ should also work)
- **Git** (for cloning the repository)
- **pip** (usually comes with Python)
- **5-10 minutes** of your time

Optional:
- **Make** (for convenient commands)
- **Docker** (for containerized deployment)

## ⚡️ Quick Start (30 seconds)

The absolute fastest way to get started:

```bash
# 1. Navigate to the project directory
cd edge-detection

# 2. Run the setup script
./setup.sh

# 3. Run the app
./run_simple.sh
```

That's it! Your browser should open to `http://localhost:8501`

---

## 📚 Detailed Installation

### Step 1: Clone the Repository (if needed)

```bash
git clone <repository-url>
cd edge-detection
```

### Step 2: Choose Your Setup Method

#### Option A: Automated Setup Script (Recommended)

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

This will:
- Check Python version
- Create a virtual environment
- Install all dependencies

#### Option B: Manual Setup

```bash
# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On macOS/Linux
# OR
venv\Scripts\activate     # On Windows

# Upgrade pip
pip install --upgrade pip

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

#### Option C: Using Make

```bash
make setup
```

### Step 3: Run the Application

#### Option A: Quick Run Script

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

#### Option B: Manual Run

```bash
source venv/bin/activate  # Activate virtual environment
streamlit run app.py
```

#### Option C: Using Make

```bash
make run
```

### Step 4: Open in Browser

The app should automatically open in your default browser at:
```
http://localhost:8501
```

If it doesn't open automatically, manually navigate to that URL.

---

## 🎓 First Steps in the Demo

Once the app is running:

1. **Upload an Image** (optional)
   - Look in the sidebar
   - Click "Upload your own image"
   - Or use the default generated image

2. **Try Different Methods**
   - Select "Sobel" from the dropdown
   - Observe the edge detection results
   - Try adjusting the kernel size
   - Enable "Show Gradient Components"

3. **Explore Prewitt and Roberts**
   - Switch methods and compare results
   - Notice differences in edge quality and noise sensitivity

4. **Experiment with Laplacian**
   - Observe the isotropic response
   - See why pre-smoothing is important
   - Try different kernel sizes

5. **Master Canny**
   - Adjust low and high thresholds
   - Observe edge connectivity
   - Compare with simpler methods using comparison mode

6. **Read Educational Content**
   - Click on the four tabs at the bottom
   - Read the explanations
   - Understand the mathematical foundations

---

## 🔧 Troubleshooting

### Problem: "Python not found"

**Solution:**
```bash
# Check if Python is installed
python3 --version

# If not, install Python 3.11+ from python.org
```

### Problem: "Permission denied" when running scripts

**Solution:**
```bash
chmod +x *.sh
```

### Problem: Import errors when running

**Solution:**
```bash
# Make sure you're in the virtual environment
source venv/bin/activate

# Reinstall requirements
pip install --force-reinstall -r requirements.txt
```

### Problem: "Port 8501 already in use"

**Solution:**
```bash
# Find and kill the process using the port
lsof -ti:8501 | xargs kill

# Or run on a different port
streamlit run app.py --server.port 8502
```

### Problem: Images not displaying

**Solution:**
- Check internet connection (for HuggingFace download)
- The app will automatically fall back to a generated image
- Try uploading your own image via the sidebar

### Problem: Slow performance

**Solution:**
- Use smaller images (app auto-resizes to 512px)
- Close other applications
- Try simpler methods (Roberts, Sobel) instead of Canny

---

## 🎯 Next Steps

### For Students
- Work through the educational tabs systematically
- Try uploading different types of images (portraits, landscapes, text)
- Compare all five methods on the same image
- Answer the discussion questions in PROJECT_SUMMARY.md

### For Instructors
- Review QUICKSTART.md for teaching tips
- Customize the app (see CONTRIBUTING.md)
- Deploy to Hugging Face Spaces (see below)
- Share with your class

### For Developers
- Read CONTRIBUTING.md for development guidelines
- Check out PROJECT_SUMMARY.md for technical details
- Consider adding new features (multi-scale, learning-based methods)

---

## 🚀 Deploying to Hugging Face Spaces

Want to share this with others online?

### Step 1: Create a Hugging Face Account
- Go to https://huggingface.co/join
- Sign up for free

### Step 2: Create a New Space
- Go to https://huggingface.co/new-space
- Choose "Streamlit" as the SDK
- Make it public (for educational use)

### Step 3: Deploy

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

Follow the prompts and enter your Space name (e.g., "username/edge-detection-demo").

Your demo will be live at: `https://huggingface.co/spaces/username/edge-detection-demo`

---

## 🐳 Docker Deployment (Advanced)

If you prefer Docker:

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

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

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

---

## 📝 Common Commands Reference

```bash
# Setup and installation
./setup.sh              # Initial setup
make setup             # Alternative using make

# Running the app
./run_simple.sh        # Quick run
make run               # Alternative using make
streamlit run app.py   # Direct run

# Testing
python test_setup.py   # Verify installation
make test             # Alternative using make

# Deployment
./deploy.sh            # Deploy to HuggingFace
make deploy           # Alternative using make

# Cleanup
make clean            # Remove virtual environment
```

---

## 💡 Tips for Best Experience

1. **Image Selection**: Use images with clear edges (buildings, objects, text)
2. **Pre-processing**: Enable Gaussian blur for noisy images
3. **Parameter Tuning**: Start with default values, then experiment
4. **Comparison**: Use comparison mode to understand differences
5. **Educational Content**: Read tabs in order (What Are Edges? → Gradient Methods → Canny → Practical)

---

## 📖 Learning Path

**Beginner** (1-2 hours):
1. Read "What Are Edges?" tab
2. Try Roberts and Sobel
3. Compare results on sample image
4. Upload your own image

**Intermediate** (2-4 hours):
1. Study gradient-based methods tab
2. Experiment with all five methods
3. Enable gradient visualizations
4. Try different kernel sizes
5. Read Canny algorithm tab

**Advanced** (4+ hours):
1. Study practical considerations tab
2. Tune Canny parameters systematically
3. Compare methods quantitatively
4. Test on domain-specific images
5. Consider implementing improvements

---

## 🆘 Getting Help

- **Documentation**: Check README.md, QUICKSTART.md, PROJECT_SUMMARY.md
- **GitHub Issues**: Report bugs or request features
- **Discussion Board**: Ask questions about edge detection concepts

---

## ✅ Verification

To verify everything is working correctly:

```bash
python test_setup.py
```

This will check:
- All dependencies are installed
- App structure is correct
- Edge detection functions work
- Visualizations render properly

---

**Ready to explore edge detection?** Run `./run_simple.sh` and start learning! 🚀