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:

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

git clone <repository-url>
cd edge-detection

Step 2: Choose Your Setup Method

Option A: Automated Setup Script (Recommended)

chmod +x setup.sh
./setup.sh

This will:

• Check Python version
• Create a virtual environment
• Install all dependencies

Option B: Manual Setup

# 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

make setup

Step 3: Run the Application

Option A: Quick Run Script

chmod +x run_simple.sh
./run_simple.sh

Option B: Manual Run

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

Option C: Using Make

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:

# Check if Python is installed
python3 --version

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

Problem: "Permission denied" when running scripts

Solution:

chmod +x *.sh

Problem: Import errors when running

Solution:

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

# 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

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:

# 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

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

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! 🚀