updated UI

.gitignore

@@ -1,2 +1,38 @@
-.venv/*
-/.streamlit/secrets.toml
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Streamlit
+.streamlit/secrets.toml
+.streamlit/config.toml
+
+# uv
+.uv/
+uv.lock
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/

.python-version

@@ -0,0 +1 @@
+3.11.9

CONTRIBUTING.md

@@ -0,0 +1,273 @@
+# CONTRIBUTING.md
+
+## 🛠️ Development Setup
+
+This project uses [uv](https://github.com/astral-sh/uv) for fast, reliable Python package management.
+
+### Prerequisites
+
+- Python 3.11 or higher
+- Git
+
+### Quick Start
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/amithjkamath/template-matching.git
+   cd template-matching
+   ```
+
+2. **Run setup**
+   ```bash
+   ./setup.sh
+   ```
+   
+   Or if you prefer using Make:
+   ```bash
+   make setup
+   ```
+
+3. **Run the app locally**
+   ```bash
+   ./run_local.sh
+   # or
+   make run
+   ```
+
+### Manual Setup
+
+If you prefer to set things up manually:
+
+1. **Install uv** (if not already installed)
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+2. **Install dependencies**
+   ```bash
+   uv sync --no-build-isolation
+   ```
+
+3. **Run the app**
+   ```bash
+   uv run --no-build-isolation streamlit run app.py
+   ```
+
+### Alternative Simple Method
+
+If you encounter build-related issues, you can use a simpler approach:
+
+```bash
+# Install dependencies
+uv pip install -r requirements.txt
+
+# Run the app
+uv run streamlit run app.py
+```
+
+## 📋 Available Commands
+
+### Using Shell Scripts
+
+- `./setup.sh` - Initial setup (install uv and dependencies)
+- `./run_local.sh` - Run the app locally
+- `./deploy.sh` - Deploy to HuggingFace Spaces
+
+### Using Makefile
+
+- `make help` - Show all available commands
+- `make setup` - Initial setup
+- `make install` - Install/update dependencies
+- `make run` - Run the app locally
+- `make deploy` - Deploy to HuggingFace
+- `make clean` - Clean up cache and temporary files
+- `make format` - Format code (requires black)
+- `make lint` - Run linting checks (requires ruff)
+- `make update` - Update all dependencies
+- `make info` - Show project information
+
+## 🧪 Testing Locally
+
+Before deploying, always test your changes locally:
+
+1. Run the app: `./run_local.sh`
+2. Open your browser to http://localhost:8501
+3. Test all interactive features
+4. Check console for any errors
+
+## 🚀 Deployment Process
+
+The app is deployed to HuggingFace Spaces. To deploy:
+
+1. **Ensure all changes are committed**
+   ```bash
+   git status
+   git add .
+   git commit -m "Your commit message"
+   ```
+
+2. **Deploy**
+   ```bash
+   ./deploy.sh
+   # or
+   make deploy
+   ```
+
+The script will:
+- Check for uncommitted changes
+- Push to the remote repository
+- HuggingFace Spaces will automatically rebuild
+
+## 📦 Dependency Management
+
+### Adding a new dependency
+
+1. **Add to pyproject.toml**
+   ```toml
+   dependencies = [
+       "new-package>=1.0.0",
+       ...
+   ]
+   ```
+
+2. **Update requirements.txt** (for HuggingFace Spaces)
+   ```
+   new-package>=1.0.0
+   ```
+
+3. **Sync dependencies**
+   ```bash
+   uv sync --no-build-isolation
+   # or
+   make install
+   ```
+
+### Updating dependencies
+
+```bash
+uv sync --upgrade --no-build-isolation
+# or
+make update
+```
+
+## 🎨 Code Style
+
+- Follow PEP 8 guidelines
+- Use meaningful variable names
+- Add docstrings to functions
+- Keep functions focused and small
+
+### Formatting (optional)
+
+Install formatting tools:
+```bash
+uv add --dev black ruff
+```
+
+Format code:
+```bash
+make format
+```
+
+Lint code:
+```bash
+make lint
+```
+
+## 📝 Making Changes
+
+1. Create a new branch for your feature
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes
+
+3. Test locally
+   ```bash
+   make run
+   ```
+
+4. Commit your changes
+   ```bash
+   git add .
+   git commit -m "Description of changes"
+   ```
+
+5. Push and create a pull request (if working with others)
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. Or merge to main and deploy
+   ```bash
+   git checkout main
+   git merge feature/your-feature-name
+   make deploy
+   ```
+
+## 🐛 Troubleshooting
+
+### Module not found error
+
+If you see `ModuleNotFoundError`:
+```bash
+uv sync --no-build-isolation  # or make install
+# Alternative:
+uv pip install -r requirements.txt
+```
+
+### Build backend errors
+
+The project is configured to skip build steps. If you still encounter hatchling/build errors:
+```bash
+./run_simple.sh
+# or use pip directly:
+uv pip install -r requirements.txt
+uv run streamlit run app.py
+```
+
+### Port already in use
+
+If port 8501 is already in use:
+```bash
+uv run --no-build-isolation streamlit run app.py --server.port 8502
+```
+
+### uv not found
+
+Make sure uv is in your PATH. After installation, restart your terminal or run:
+```bash
+source ~/.cargo/env
+```
+
+## 📚 Project Structure
+
+```
+template-matching/
+├── app.py                 # Main Streamlit application
+├── requirements.txt       # Dependencies for HuggingFace Spaces
+├── pyproject.toml        # Python project configuration (uv)
+├── Dockerfile            # Docker configuration for HF Spaces
+├── packages.txt          # System packages for HF Spaces
+├── README.md             # User-facing documentation
+├── CONTRIBUTING.md       # This file - developer documentation
+├── LICENSE               # MIT License
+├── setup.sh              # Setup script
+├── run_local.sh          # Local run script
+├── deploy.sh             # Deployment script
+├── Makefile             # Make commands for convenience
+└── .gitignore           # Git ignore patterns
+```
+
+## 🤝 Contributing Guidelines
+
+1. Keep the educational focus in mind
+2. Maintain interactive and engaging features
+3. Test thoroughly before deploying
+4. Update documentation for any new features
+5. Keep dependencies minimal and up-to-date
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

Makefile

@@ -0,0 +1,82 @@
+# Makefile for Template Matching Demo
+.PHONY: help setup run deploy clean test format lint install
+
+# Default target
+.DEFAULT_GOAL := help
+
+# Colors
+BLUE := \033[0;34m
+GREEN := \033[0;32m
+YELLOW := \033[1;33m
+NC := \033[0m
+
+help: ## Show this help message
+	@echo "$(BLUE)Template Matching Demo - Available Commands$(NC)"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  $(GREEN)%-15s$(NC) %s\n", $$1, $$2}'
+	@echo ""
+
+setup: ## Initial setup - install uv and dependencies
+	@echo "$(BLUE)🔧 Running setup...$(NC)"
+	@chmod +x setup.sh
+	@./setup.sh
+
+install: ## Install/update dependencies using uv
+	@echo "$(BLUE)📦 Installing dependencies...$(NC)"
+	@uv sync --no-build-isolation
+	@echo "$(GREEN)✅ Dependencies installed$(NC)"
+
+run: ## Run the app locally
+	@chmod +x run_local.sh
+	@./run_local.sh
+
+deploy: ## Deploy to HuggingFace Spaces
+	@chmod +x deploy.sh
+	@./deploy.sh
+
+clean: ## Clean up cache and temporary files
+	@echo "$(BLUE)🧹 Cleaning up...$(NC)"
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	@find . -type f -name "*.pyo" -delete 2>/dev/null || true
+	@find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	@echo "$(GREEN)✅ Cleanup complete$(NC)"
+
+format: ## Format code with black and isort (if installed)
+	@echo "$(BLUE)🎨 Formatting code...$(NC)"
+	@if command -v black > /dev/null; then \
+		uv run black app.py; \
+	else \
+		echo "$(YELLOW)⚠️  black not installed, skipping$(NC)"; \
+	fi
+
+lint: ## Run linting checks
+	@echo "$(BLUE)🔍 Running linting...$(NC)"
+	@if command -v ruff > /dev/null; then \
+		uv run ruff check app.py; \
+	else \
+		echo "$(YELLOW)⚠️  ruff not installed, skipping$(NC)"; \
+	fi
+
+test: ## Run tests (if any)
+	@echo "$(BLUE)🧪 Running tests...$(NC)"
+	@echo "$(YELLOW)⚠️  No tests configured yet$(NC)"
+
+check: format lint ## Run all checks (format + lint)
+	@echo "$(GREEN)✅ All checks complete$(NC)"
+
+update: ## Update all dependencies
+	@echo "$(BLUE)⬆️  Updating dependencies...$(NC)"
+	@uv sync --upgrade --no-build-isolation
+	@echo "$(GREEN)✅ Dependencies updated$(NC)"
+
+info: ## Show project information
+	@echo "$(BLUE)📊 Project Information$(NC)"
+	@echo ""
+	@echo "  Name:        Template Matching Demo"
+	@echo "  Python:      $$(python3 --version | awk '{print $$2}')"
+	@echo "  UV:          $$(uv --version 2>/dev/null || echo 'not installed')"
+	@echo "  Repository:  https://github.com/amithjkamath/template-matching"
+	@echo "  HF Space:    https://huggingface.co/spaces/amithjkamath/template-matching"
+	@echo ""

QUICKSTART.md

@@ -0,0 +1,99 @@
+# 🚀 Quick Start Guide
+
+## First Time Setup
+
+1. **Run the setup script:**
+   ```bash
+   ./setup.sh
+   ```
+   
+   This will:
+   - Check Python version (3.11+ required)
+   - Install uv package manager if needed
+   - Install all dependencies
+   - Set script permissions
+
+## Running the App
+
+### Simple Script
+If you encounter build issues, use the simpler version:
+```bash
+./run_simple.sh
+```
+
+### Option 3: Make Command
+```bash
+make run
+```
+
+### Option 4: Direct Command
+```bash
+uv run --no-build-isolation streamlit run app.py
+```
+
+The app will open in your browser at `http://localhost:8501`
+
+## Deploying to HuggingFace Spaces
+
+### Option 1: Shell Script
+```bash
+./deploy.sh
+```
+
+### Option 2: Make Command
+```bash
+make deploy
+```
+
+The script will:
+- Check for uncommitted changes
+- Prompt you to commit if needed
+- Push to the repository
+- HuggingFace Spaces will automatically rebuild
+
+## Troubleshooting
+
+### "Build backend error" or hatchling issues
+The project is now configured to skip the build step. If you still see build errors:
+```bash
+./run_simple.sh
+# or
+uv pip install -r requirements.txt
+uv run streamlit run app.py
+```
+
+### "Module not found" error
+```bash
+uv sync --no-build-isolation
+# or
+uv pip install -r requirements.txt
+```
+
+### Port 8501 already in use
+```bash
+uv run --no-build-isolation streamlit run app.py --server.port 8502
+```
+
+### Script permission denied
+```bash
+chmod +x setup.sh run_local.sh run_simple.sh deploy.sh
+```
+
+## Available Commands
+
+Run `make help` to see all available commands:
+
+```bash
+make help        # Show all commands
+make setup       # Initial setup
+make install     # Install dependencies
+make run         # Run locally
+make deploy      # Deploy to HuggingFace
+make clean       # Clean cache files
+make update      # Update dependencies
+make info        # Show project info
+```
+
+## Need Help?
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed documentation.

README.md

@@ -6,27 +6,120 @@ colorTo: green
 sdk: docker
 pinned: false
 license: mit
-short_description: Demonstration of template matching with waldo
+short_description: Interactive demonstration of template matching with Waldo
 ---
 
-# template-matching
+# 🔍 Template Matching Demo
 
-This is a demonstration of how template matching works by computing correlation between the search space and the template. 
+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!
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## 🎯 What is Template Matching?
 
-## 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:
 
-Template Matching is a simple method where the location of a template in a scene is computed by sliding it all across the scene and computing a similarity.
+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
 
-## What situations could this method be applied to?
+## 🚀 Try It Live
 
-This method works best when the template is exactly replicated in the scene - at the same scale (size), not rotated or sheared. 
+**[Launch the Interactive Demo](https://huggingface.co/spaces/amithjkamath/template-matching)**
 
-## When would it not work?
+## ✨ Features
 
-If the template is not exactly available in the scene (when there are size or rotation or other transformation changes), this method could fail catastrophically. 
+- 🖱️ **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
 
-## Are there better similarity measures than correlation?
+## 💻 Run Locally
 
-Point based feature matching methods like SIFT, SURF, MSER and so on would work better in cases where the relative pose of the template with respect to the scene cannot be controlled.
+### Quick Start
+
+```bash
+# 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)
+
+```bash
+make setup    # Initial setup
+make run      # Run the app
+make deploy   # Deploy to HuggingFace
+make help     # See all commands
+```
+
+### Manual Setup
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies
+uv sync
+
+# Run the app
+uv run streamlit run app.py
+```
+
+## 📋 Requirements
+
+- Python 3.11 or higher
+- [uv](https://github.com/astral-sh/uv) package manager (installed by setup.sh)
+
+## 🛠️ Development
+
+See [CONTRIBUTING.md](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](CONTRIBUTING.md) for guidelines.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](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](https://www.loginradius.com/blog/engineering/guest-post/opencv-web-app-with-streamlit/)
+- [Finding Waldo: Feature Matching for OpenCV](https://medium.com/analytics-vidhya/finding-waldo-feature-matching-for-opencv-9bded7f5ab10)

app.py

@@ -1,13 +1,16 @@
 """
 Inspired by https://www.loginradius.com/blog/engineering/guest-post/opencv-web-app-with-streamlit/
-and https://medium.com/analytics-vidhya/finding-waldo-feature-matching-for-opencv-9bded7f5ab10 
+and https://medium.com/analytics-vidhya/finding-waldo-feature-matching-for-opencv-9bded7f5ab10
 """
+
 import numpy as np
 import cv2 as cv
 import streamlit as st
 from huggingface_hub import hf_hub_download
+from streamlit_image_coordinates import streamlit_image_coordinates
 
 
+@st.cache_data
 def compute_correlation(scene: np.array, template: np.array):
     """
     COMPUTE_CORRELATION computes the correlation between the pixels in scene and template
@@ -24,113 +27,359 @@ def compute_correlation(scene: np.array, template: np.array):
     return res
 
 
-def main_loop():
+def compute_patch_correlation(scene_patch: np.array, template: np.array):
     """
-    MAIN_LOOP is the main loop (duh) for this streamlit App.
+    Compute correlation score between a scene patch and template.
+    Returns a score between 0 and 1, where 1 is a perfect match.
     """
-    st.set_page_config(layout="wide")
+    # Ensure patches are the same size
+    if scene_patch.shape != template.shape:
+        return 0.0
+
+    gray_patch = cv.cvtColor(scene_patch, cv.COLOR_BGR2GRAY)
+    cv.normalize(gray_patch, gray_patch, 0, 255, cv.NORM_MINMAX)
+
+    gray_template = cv.cvtColor(template, cv.COLOR_BGR2GRAY)
+    cv.normalize(gray_template, gray_template, 0, 255, cv.NORM_MINMAX)
+
+    # Use normalized cross-correlation
+    result = cv.matchTemplate(gray_patch, gray_template, cv.TM_CCOEFF_NORMED)
+    return float(result[0, 0]) if result.size > 0 else 0.0
+
+
+def extract_patch(scene: np.array, x: int, y: int, template_shape):
+    """
+    Extract a patch from the scene centered at (x, y) with the same size as the template.
+    """
+    h, w = template_shape[0], template_shape[1]
+
+    # Calculate patch boundaries
+    y_start = max(0, y - h // 2)
+    y_end = min(scene.shape[0], y_start + h)
+    x_start = max(0, x - w // 2)
+    x_end = min(scene.shape[1], x_start + w)
+
+    # Adjust if we hit boundaries
+    if y_end - y_start < h:
+        y_start = max(0, y_end - h)
+    if x_end - x_start < w:
+        x_start = max(0, x_end - w)
+
+    patch = scene[y_start:y_end, x_start:x_end]
+
+    # Pad if necessary (edge cases)
+    if patch.shape[0] < h or patch.shape[1] < w:
+        patch = cv.copyMakeBorder(
+            patch,
+            0,
+            h - patch.shape[0],
+            0,
+            w - patch.shape[1],
+            cv.BORDER_CONSTANT,
+            value=[0, 0, 0],
+        )
+
+    return patch, (x_start, y_start, x_end, y_end)
 
-    st.title("Template Matching Demo")
-    st.subheader(
-        "This app demonstrates how a template matching algorithm works: by sliding the template across the scene!")
 
-    # Load images from Hugging Face dataset
+@st.cache_resource
+def load_images():
+    """Load and cache the template and scene images."""
+    # Load template
     template_path = hf_hub_download(
         repo_id="amithjkamath/exampleimages",
         filename="waldo-template.jpeg",
-        repo_type="dataset"
+        repo_type="dataset",
     )
     template_image = cv.imread(template_path)
     template_image = cv.cvtColor(template_image, cv.COLOR_BGR2RGB)
 
-    st.markdown(
-        "To introduce this method, let's first get introduced to our protagonist - Waldo")
-
-    st.text("Introducing Waldo!")
-    st.image(template_image, width=100)
-
-    st.markdown(
-        "Now for the fun bit - can you find Waldo in the scene below? Most of us will take about 20 seconds, if not more!")
-
+    # Load scene
     scene_path = hf_hub_download(
         repo_id="amithjkamath/exampleimages",
         filename="waldo-scene.jpeg",
-        repo_type="dataset"
+        repo_type="dataset",
     )
     scene_image = cv.imread(scene_path)
     scene_image = cv.cvtColor(scene_image, cv.COLOR_BGR2RGB)
 
-    st.text("Can you find Waldo?")
-    st.image(scene_image, width=1000)
+    return template_image, scene_image
 
+
+def main_loop():
+    """
+    MAIN_LOOP is the main loop (duh) for this streamlit App.
+    """
+    st.set_page_config(layout="wide")
+
+    st.title("🔍 Interactive Template Matching Demo")
     st.markdown(
-        "Can a computer do better? Certainly. The template matching algorithm is conceptually really simple.")
-    st.markdown(
-        "The idea is to hold the template over all possible patches in the scene, and then compute a similarity.")
-    st.markdown(
-        "Naturally, the similarity will be the highest when the template matches what's in the patch underneath.")
+        """
+    Welcome! This app teaches you how **template matching** works - a fundamental computer vision technique.
+    You'll learn by doing: click and drag the template around to see how computers "find" objects in images!
+    """
+    )
+
+    # Load images (cached)
+    template_image, scene_image = load_images()
+
+    # Introduction
+    col1, col2 = st.columns([1, 3])
+
+    with col1:
+        st.markdown("### Meet Waldo 👋")
+        st.image(template_image, caption="Our template to find")
+        st.markdown(
+            "**Template size:** {}×{}".format(
+                template_image.shape[1], template_image.shape[0]
+            )
+        )
+
+    with col2:
+        st.markdown("### The Challenge")
+        st.markdown(
+            """
+        Can you spot Waldo in this busy scene? Most people take 20+ seconds!
+        
+        But computers can do it differently. Instead of using intuition, they use **template matching**:
+        - Slide the template over every possible position
+        - At each position, compute a **similarity score**
+        - The highest score reveals where Waldo is!
+        """
+        )
+
+    # Show the scene
+    st.markdown("---")
+    st.markdown("### 🎯 Try It Yourself: Interactive Template Matching")
     st.markdown(
-        "We could then record the location of the maximum similarity, and return it when we have scanned everywhere.")
-
-    corr = compute_correlation(scene_image, template_image)
-    norm_corr = (corr - corr.min()) / (corr.max() - corr.min())
-    st.text("Here's the correlation image:")
-    st.image(norm_corr, width=1000)
-
-    result_image = scene_image.copy()
-    threshold = 0.6
-    # finding the values where it exceeds the threshold
-    loc = np.where(corr >= threshold)
-    template_shape = template_image.shape[::-1]  # 3, W, H
-    for pt in zip(*loc[::-1]):
-        # draw rectangle on places where it exceeds threshold
+        """
+    **Instructions:** Click anywhere on the image below to place the template there. 
+    Watch how the correlation score changes! Can you find where Waldo actually is?
+    """
+    )
+
+    # Initialize session state for template position
+    if "template_x" not in st.session_state:
+        st.session_state.template_x = scene_image.shape[1] // 4
+        st.session_state.template_y = scene_image.shape[0] // 4
+
+    if "last_computed_x" not in st.session_state:
+        st.session_state.last_computed_x = st.session_state.template_x
+        st.session_state.last_computed_y = st.session_state.template_y
+
+    if "computed_score" not in st.session_state:
+        st.session_state.computed_score = None
+
+    if "computed_patch" not in st.session_state:
+        st.session_state.computed_patch = None
+
+    # Create interactive image
+    col_left, col_right = st.columns([2, 1])
+
+    with col_left:
+        st.markdown("**Click on the image to move the template:**")
+
+        # Create overlay image with template
+        display_image = scene_image.copy()
+        t_h, t_w = template_image.shape[0], template_image.shape[1]
+
+        # Calculate template position (top-left corner)
+        x = st.session_state.template_x
+        y = st.session_state.template_y
+        x_start = max(0, x - t_w // 2)
+        y_start = max(0, y - t_h // 2)
+        x_end = min(scene_image.shape[1], x_start + t_w)
+        y_end = min(scene_image.shape[0], y_start + t_h)
+
+        # Draw rectangle around template position
         cv.rectangle(
-            result_image, pt, (pt[0] + template_shape[1], pt[1] + template_shape[2]), (0, 255, 0), 2)
+            display_image, (x_start, y_start), (x_end, y_end), (255, 255, 0), 3
+        )
+
+        # Overlay semi-transparent template
+        overlay = display_image.copy()
+        if y_end - y_start == t_h and x_end - x_start == t_w:
+            overlay[y_start:y_end, x_start:x_end] = cv.addWeighted(
+                overlay[y_start:y_end, x_start:x_end], 0.5, template_image, 0.5, 0
+            )
+            display_image = cv.addWeighted(display_image, 0.7, overlay, 0.3, 0)
+
+        # Get click coordinates
+        value = streamlit_image_coordinates(display_image, key="scene_image")
+
+        # Update position only if clicked (value changed)
+        if value is not None:
+            new_x = value["x"]
+            new_y = value["y"]
+            # Only update if position actually changed
+            if (
+                new_x != st.session_state.template_x
+                or new_y != st.session_state.template_y
+            ):
+                st.session_state.template_x = new_x
+                st.session_state.template_y = new_y
 
-    st.text("Here's the result:")
-    st.image(result_image, width=1000)
+    with col_right:
+        # Show current position
+        st.markdown("### 📍 Current Position")
+        st.markdown(f"**X:** {st.session_state.template_x}px")
+        st.markdown(f"**Y:** {st.session_state.template_y}px")
 
-    st.markdown("How does this work? The template slides across the scene, and \
-                 computes the correlation at each location. Use the slider below \
-                 to see how this works!")
+        # Check if position has changed since last computation
+        position_changed = (
+            st.session_state.template_x != st.session_state.last_computed_x
+            or st.session_state.template_y != st.session_state.last_computed_y
+        )
 
-    alpha = st.slider('Move to slide the template', 0.0,
-                      1.0, value=0.00, step=0.0001)
-    scene_image = scene_image * 0.25
-    scene_image = scene_image.astype(np.uint8)
+        # Button to compute match
+        if position_changed:
+            st.info("🔄 Position changed! Click below to compute match score.")
 
-    norm_corr = cv.copyMakeBorder(norm_corr,
-                                  template_shape[2]//2, template_shape[2]//2,
-                                  template_shape[1]//2, template_shape[1]//2,
-                                  cv.BORDER_CONSTANT)
-    norm_corr = cv.multiply(255.0, norm_corr)
-    norm_corr = np.dstack((norm_corr, norm_corr, norm_corr))
+        compute_button = st.button(
+            "🔍 Compute Match Score", type="primary", use_container_width=True
+        )  # Will be updated to width='stretch' in future
 
-    out_image = scene_image.copy()
-    out_shape = out_image.shape  # H, W, 3
-    range_movement = (out_shape[1] - template_shape[1]) * \
-        (out_shape[0] - template_shape[2])
+        # Compute correlation if button clicked or initial load
+        if compute_button or st.session_state.computed_score is None:
+            with st.spinner("Computing correlation..."):
+                # Extract patch and compute correlation
+                patch, _ = extract_patch(
+                    scene_image,
+                    st.session_state.template_x,
+                    st.session_state.template_y,
+                    template_image.shape[:2],
+                )
 
-    absolute_loc = np.int32(alpha * range_movement)
-    absolute_loc_y = absolute_loc // (out_shape[1] - template_shape[1])
-    absolute_loc_x = absolute_loc % (out_shape[0] - template_shape[2])
-    out_image[0:absolute_loc_y, :, :] = norm_corr[0:absolute_loc_y, :, :]
+                score = compute_patch_correlation(patch, template_image)
 
-    out_image[absolute_loc_y:(absolute_loc_y + template_shape[2]),
-              absolute_loc_x:(absolute_loc_x + template_shape[1]), :] = template_image
+                # Store computed values
+                st.session_state.computed_score = score
+                st.session_state.computed_patch = patch
+                st.session_state.last_computed_x = st.session_state.template_x
+                st.session_state.last_computed_y = st.session_state.template_y
 
-    if absolute_loc_y > (pt[1] + template_shape[2]):
-        for pt in zip(*loc[::-1]):
-            # draw rectangle on places where it exceeds threshold
-            cv.rectangle(
-                out_image, pt, (pt[0] + template_shape[1], pt[1] + template_shape[2]), (0, 255, 0), 2)
+        # Display match score with color coding
+        st.markdown("### 📊 Match Score")
 
-    st.text("Here's how the correlation is computed:")
-    st.image(out_image, width=1000)
+        if st.session_state.computed_score is not None:
+            score = st.session_state.computed_score
 
-    st.markdown("Image copyrights for Where is Waldo - fully attributed to original owners. \
-                 It is used here purely for educational purposes.")
+            # Determine match quality
+            if score >= 0.8:
+                quality = "🎉 Excellent Match!"
+                color = "green"
+                explanation = "This is very likely the correct location!"
+            elif score >= 0.6:
+                quality = "✅ Good Match"
+                color = "blue"
+                explanation = "Strong similarity, but maybe not perfect."
+            elif score >= 0.4:
+                quality = "⚠️ Moderate Match"
+                color = "orange"
+                explanation = "Some similarity, but probably not the right spot."
+            else:
+                quality = "❌ Poor Match"
+                color = "red"
+                explanation = "Very low similarity - keep searching!"
+
+            # Display score with highlighting
+            st.markdown(
+                f"""
+            <div style="background-color: {color}; padding: 20px; border-radius: 10px; text-align: center;">
+                <h2 style="color: white; margin: 0;">{score:.3f}</h2>
+                <p style="color: white; margin: 5px 0 0 0; font-size: 18px;"><b>{quality}</b></p>
+            </div>
+            """,
+                unsafe_allow_html=True,
+            )
+
+            st.markdown(f"*{explanation}*")
+        else:
+            st.warning("Click 'Compute Match Score' to analyze this position.")
+
+        # Show zoomed comparison
+        st.markdown("### 🔬 Close-up Comparison")
+
+        if st.session_state.computed_patch is not None:
+            st.markdown("**Template vs Current Patch:**")
+
+            # Create side-by-side comparison
+            comparison = np.hstack([template_image, st.session_state.computed_patch])
+            st.image(
+                comparison,
+                caption="Left: Template | Right: Current patch",
+                width="stretch",
+            )
+        else:
+            st.info("Compute match score to see the comparison.")
+
+    # Educational section: Show the full correlation heatmap
+    st.markdown("---")
+    st.markdown("### 🧠 How Does the Computer Find Waldo?")
+
+    with st.expander("Click here to see the full solution!", expanded=False):
+        st.markdown(
+            """
+        The computer doesn't guess - it's systematic! It computes the correlation score at **every possible position**.
+        Here's the resulting **correlation heatmap** where brighter areas indicate better matches:
+        """
+        )
+
+        corr = compute_correlation(scene_image, template_image)
+        norm_corr = (corr - corr.min()) / (corr.max() - corr.min())
+
+        col1, col2 = st.columns(2)
+
+        with col1:
+            st.image(
+                norm_corr,
+                caption="Correlation Heatmap (bright = high match)",
+                width="stretch",
+            )
+            st.markdown("Notice the bright spot? That's where Waldo is! 🎯")
+
+        with col2:
+            # Show result with bounding boxes
+            result_image = scene_image.copy()
+            threshold = 0.6
+            loc = np.where(corr >= threshold)
+            template_shape = template_image.shape
+
+            for pt in zip(*loc[::-1]):
+                cv.rectangle(
+                    result_image,
+                    pt,
+                    (pt[0] + template_shape[1], pt[1] + template_shape[0]),
+                    (0, 255, 0),
+                    3,
+                )
+
+            st.image(
+                result_image,
+                caption="Detected locations (green boxes)",
+                width="stretch",
+            )
+            st.markdown("Green boxes show all locations with correlation > 0.6")
+
+        st.markdown(
+            """
+        **Key Insight:** Template matching is a brute-force approach that checks every possible location.
+        While simple, it's very effective for finding exact or near-exact matches!
+        """
+        )
+
+    # Footer
+    st.markdown("---")
+    st.markdown(
+        """
+    <small>
+    🎨 Image copyrights for "Where's Waldo?" are fully attributed to original owners.  
+    Used here purely for educational purposes.
+    </small>
+    """,
+        unsafe_allow_html=True,
+    )
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main_loop()

deploy.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Script to deploy the app to HuggingFace Spaces
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🚀 Deploying Template Matching Demo to HuggingFace Spaces...${NC}"
+
+# Check if we're in a git repository
+if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+    echo -e "${RED}❌ Not a git repository${NC}"
+    exit 1
+fi
+
+# Check if there are uncommitted changes
+if ! git diff-index --quiet HEAD --; then
+    echo -e "${YELLOW}⚠️  You have uncommitted changes. Please commit them first.${NC}"
+    echo ""
+    echo "Uncommitted files:"
+    git status --short
+    echo ""
+    read -p "Do you want to commit all changes now? (y/n) " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        read -p "Enter commit message: " commit_msg
+        git add .
+        git commit -m "$commit_msg"
+        echo -e "${GREEN}✅ Changes committed${NC}"
+    else
+        echo -e "${RED}❌ Deployment cancelled. Please commit your changes first.${NC}"
+        exit 1
+    fi
+fi
+
+# Get current branch
+current_branch=$(git branch --show-current)
+echo -e "${BLUE}📍 Current branch: ${current_branch}${NC}"
+
+# Check if we're on main/master branch
+if [[ "$current_branch" != "main" && "$current_branch" != "master" ]]; then
+    echo -e "${YELLOW}⚠️  Warning: You're not on the main/master branch${NC}"
+    read -p "Continue anyway? (y/n) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo -e "${RED}❌ Deployment cancelled${NC}"
+        exit 1
+    fi
+fi
+
+# Push to origin
+echo -e "${BLUE}📤 Pushing to remote repository...${NC}"
+git push origin $current_branch
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}✅ Successfully deployed to HuggingFace Spaces!${NC}"
+    echo ""
+    echo -e "${BLUE}🌐 Your space should update automatically at:${NC}"
+    echo -e "${GREEN}   https://huggingface.co/spaces/amithjkamath/template-matching${NC}"
+    echo ""
+    echo -e "${YELLOW}💡 Note: It may take a few minutes for the changes to appear.${NC}"
+else
+    echo -e "${RED}❌ Failed to push to remote repository${NC}"
+    echo "Please check your git configuration and remote settings."
+    exit 1
+fi

pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "template-matching"
+version = "0.1.0"
+description = "Interactive template matching demo using OpenCV and Streamlit"
+readme = "README.md"
+requires-python = ">=3.11.9"
+dependencies = [
+    "opencv-python-headless>=4.8.0",
+    "streamlit>=1.28.0",
+    "streamlit-image-coordinates>=0.1.6",
+    "pillow>=10.0.0",
+    "numpy>=1.24.0",
+    "huggingface-hub>=0.17.0",
+]
+
+[tool.pylint."MESSAGES CONTROL"]
+disable = ["c-extension-no-member"]
+
+[tool.pyright]
+reportGeneralTypeIssues = false
+reportOptionalMemberAccess = false

requirements.txt

@@ -1,5 +1,6 @@
 opencv-python-headless
 streamlit
+streamlit-image-coordinates
 Pillow
 numpy
 huggingface_hub

run_simple.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Alternative simple run script using uv pip directly
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🚀 Starting Template Matching Demo locally...${NC}"
+
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo "❌ uv is not installed. Please install it first:"
+    echo "   curl -LsSf https://astral.sh/uv/install.sh | sh"
+    exit 1
+fi
+
+# Install dependencies if needed
+echo -e "${BLUE}📦 Checking dependencies...${NC}"
+uv pip install -q -r requirements.txt
+
+# Run the Streamlit app
+echo -e "${GREEN}✅ Starting Streamlit app...${NC}"
+echo -e "${BLUE}🌐 The app will open at http://localhost:8501${NC}"
+echo ""
+
+uv run streamlit run app.py
+
+# If the app exits
+echo -e "${BLUE}👋 App stopped.${NC}"

setup.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Setup script for Template Matching Demo
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🔧 Setting up Template Matching Demo...${NC}"
+echo ""
+
+# Check Python version
+echo -e "${BLUE}🐍 Checking Python version...${NC}"
+python_version=$(python3 --version 2>&1 | awk '{print $2}')
+required_version="3.11.9"
+
+if python3 -c "import sys; exit(0 if sys.version_info >= (3, 11) else 1)"; then
+    echo -e "${GREEN}✅ Python ${python_version} is installed${NC}"
+else
+    echo -e "${RED}❌ Python 3.11+ is required${NC}"
+    exit 1
+fi
+
+# Check if uv is installed
+echo -e "${BLUE}📦 Checking for uv package manager...${NC}"
+if ! command -v uv &> /dev/null; then
+    echo -e "${YELLOW}⚠️  uv is not installed${NC}"
+    echo -e "${BLUE}Installing uv...${NC}"
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    
+    # Source the shell configuration to make uv available
+    if [ -f "$HOME/.cargo/env" ]; then
+        source "$HOME/.cargo/env"
+    fi
+    
+    if command -v uv &> /dev/null; then
+        echo -e "${GREEN}✅ uv installed successfully${NC}"
+    else
+        echo -e "${RED}❌ Failed to install uv. Please install manually:${NC}"
+        echo "   curl -LsSf https://astral.sh/uv/install.sh | sh"
+        exit 1
+    fi
+else
+    echo -e "${GREEN}✅ uv is already installed${NC}"
+fi
+
+# Sync dependencies
+echo ""
+echo -e "${BLUE}📥 Installing dependencies...${NC}"
+uv sync --no-build-isolation
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}✅ Dependencies installed successfully${NC}"
+else
+    echo -e "${RED}❌ Failed to install dependencies${NC}"
+    exit 1
+fi
+
+# Make scripts executable
+echo ""
+echo -e "${BLUE}🔐 Setting script permissions...${NC}"
+chmod +x run_local.sh deploy.sh setup.sh
+
+echo ""
+echo -e "${GREEN}✅ Setup complete!${NC}"
+echo ""
+echo -e "${BLUE}Next steps:${NC}"
+echo "  1. Run locally:  ${GREEN}./run_local.sh${NC}"
+echo "  2. Deploy:       ${GREEN}./deploy.sh${NC}"
+echo ""
+echo -e "${YELLOW}💡 Tip: You can also use 'make run' or 'make deploy' if you prefer${NC}"