README.md

metadata

title: Template Matching Demo
emoji: 🔍
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
short_description: Interactive demonstration of template matching with Waldo

🔍 Template Matching Demo

An interactive educational tool that demonstrates how template matching works using computer vision. Learn by doing - click and drag to explore how computers find objects in images!

🎯 What is Template Matching?

Template Matching is a simple yet powerful computer vision method that finds the location of a template image within a larger scene by:

1. Sliding the template across all possible positions in the scene
2. Computing a similarity score at each position
3. Identifying the location with the highest similarity score

🚀 Try It Live

Launch the Interactive Demo

✨ Features

• 🖱️ Interactive Template Placement: Click anywhere on the image to test template matching
• 📊 Real-time Correlation Scores: See quantitative match scores (0.0-1.0) with color coding
• 🔬 Zoomed Comparison View: Side-by-side visualization of template vs. current patch
• 🎨 Educational Heatmaps: Understand how correlation works across the entire scene
• 🎯 Instant Feedback: Learn through exploration and immediate visual feedback

💻 Run Locally

Quick Start

# Clone the repository
git clone https://github.com/amithjkamath/template-matching.git
cd template-matching

# Run setup (installs uv and dependencies)
./setup.sh

# Run the app
./run_local.sh

Using Make (Alternative)

make setup    # Initial setup
make run      # Run the app
make deploy   # Deploy to GitHub & HuggingFace
make help     # See all commands

Manual Setup

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync --no-build-isolation

# Run the app
uv run --no-build-isolation streamlit run app.py

📋 Requirements

• Python 3.11 or higher
• uv package manager (installed by setup.sh)

🛠️ Development

See CONTRIBUTING.md for detailed development setup and guidelines.

📚 What situations could this method be applied to?

Template matching works best when:

• ✅ The template is exactly replicated in the scene
• ✅ Same scale (size) and orientation
• ✅ No rotation or geometric transformations
• ✅ Similar lighting conditions

⚠️ When would it not work?

Template matching struggles with:

• ❌ Scale changes (different sizes)
• ❌ Rotation or perspective changes
• ❌ Significant lighting/color differences
• ❌ Partial occlusions

🔬 Better Alternatives?

For scenarios with transformations, consider feature-based matching methods:

• SIFT (Scale-Invariant Feature Transform)
• SURF (Speeded-Up Robust Features)
• ORB (Oriented FAST and Rotated BRIEF)
• AKAZE (Accelerated-KAZE)

These methods are more robust to scale, rotation, and illumination changes.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎨 Image Attribution

Images from "Where's Waldo?" are copyrighted by their original owners and are used here purely for educational purposes.

🙏 Acknowledgments

Inspired by:

• OpenCV Web App with Streamlit
• Finding Waldo: Feature Matching for OpenCV