feat: initial gradio app

.gitattributes

@@ -1,3 +1,12 @@
+# Images (catalog and examples)
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.JPG filter=lfs diff=lfs merge=lfs -text
+*.JPEG filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.PNG filter=lfs diff=lfs merge=lfs -text
+
+# Archives and models
 *.7z filter=lfs diff=lfs merge=lfs -text
 *.arrow filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+uv.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Models (downloaded at runtime)
+data/models/
+
+# Extracted data (regenerated from archives on first run)
+data/catalog/
+cached_results/
+
+# Keep archives tracked (these are the source of truth)
+!data/catalog.tar.gz
+!data/cache.tar.gz
+
+# Temp files
+*.tmp
+*.temp
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Logs
+*.log

Makefile

@@ -0,0 +1,31 @@
+.PHONY: help install run clean create-archives extract-data precompute-cache archive-info
+
+help:  ## Show this help message
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Available targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install dependencies with uv
+	uv sync
+
+run:  ## Run the Gradio app locally
+	uv run python app.py
+
+clean:  ## Clean up temporary files and caches
+	rm -rf .venv uv.lock
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+	find . -type f -name "*.pyo" -delete
+
+create-archives:  ## Create compressed archives from catalog and cache
+	uv run python scripts/create_archives.py
+
+extract-data:  ## Extract archives (done automatically on first run)
+	uv run python -c "from snowleopard_reid.data_setup import ensure_data_extracted; ensure_data_extracted()"
+
+precompute-cache:  ## Run pipeline on all examples to generate cache
+	uv run python scripts/precompute_cache.py
+
+archive-info:  ## Show info about archives and directories
+	uv run python scripts/create_archives.py --info

README.md

@@ -1,13 +1,56 @@
 ---
-title: Snowleopard Reid
-emoji: 🐠
+title: Snowleopard reID
+emoji: 🐆
 colorFrom: blue
 colorTo: indigo
 sdk: gradio
-sdk_version: 6.0.1
+sdk_version: 5.49.1
+python_version: 3.11
 app_file: app.py
 pinned: false
-short_description: snow leopard reID using AI
+short_description: Snow Leopard reID using AI
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Snow Leopard Re-Identification
+
+AI-powered snow leopard re-identification system using computer vision and deep learning.
+
+## Features
+
+- **Single Image Matching**: Upload an image to identify individual snow leopards against a catalog
+- **Batch Processing**: Process multiple images at once with filtering options
+- **Multiple Detection Methods**: YOLO or Grounding DINO + SAM HQ for segmentation
+- **Multiple Matching Algorithms**: SIFT, SuperPoint, DISK, or ALIKED feature extractors
+
+## Local Development
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Setup
+
+```bash
+# Install dependencies
+make install
+
+# Run the app locally
+make run
+```
+
+The app will be available at `http://localhost:7860`.
+
+## Data
+
+- **Catalog**: Pre-computed features for known snow leopards (stored with Git LFS)
+- **SAM HQ Model**: Downloaded automatically at runtime from HuggingFace Hub
+
+## Tech Stack
+
+- Gradio for the web interface
+- PyTorch for deep learning
+- Grounding DINO for zero-shot object detection
+- SAM HQ (Segment Anything Model High Quality) for segmentation
+- LightGlue for feature matching
+- Wasserstein distance for match scoring

app.py

@@ -0,0 +1,1608 @@
+"""Gradio web application for snow leopard identification and catalog exploration.
+
+This interactive web interface provides an easy-to-use frontend for the snow
+leopard identification system. Users can upload images, view matches against the catalog,
+and explore reference leopards through a browser-based UI powered by Gradio.
+
+Features:
+- Upload snow leopard images or select from examples
+- Run full identification pipeline with GDINO+SAM segmentation
+- View top-K matches with Wasserstein distance scores
+- Explore complete leopard catalog with thumbnails
+- Visualize matched keypoints between query and catalog images
+
+Usage:
+    # Local testing with uv:
+    uv sync
+    uv run python app.py
+
+    # Deployed on Hugging Face Spaces
+"""
+
+import sys
+from pathlib import Path
+
+# Add src to path for imports BEFORE importing snowleopard_reid
+SPACE_ROOT = Path(__file__).parent
+sys.path.insert(0, str(SPACE_ROOT / "src"))
+
+import logging
+import shutil
+import tempfile
+from dataclasses import dataclass
+
+import cv2
+import gradio as gr
+import numpy as np
+import torch
+import yaml
+from huggingface_hub import hf_hub_download
+from PIL import Image
+
+from snowleopard_reid.catalog import (
+    get_available_body_parts,
+    get_available_locations,
+    get_catalog_metadata_for_id,
+    load_catalog_index,
+    load_leopard_metadata,
+)
+from snowleopard_reid.pipeline.stages import (
+    run_feature_extraction_stage,
+    run_matching_stage,
+    run_preprocess_stage,
+    run_segmentation_stage,
+    select_best_mask,
+)
+from snowleopard_reid.pipeline.stages.segmentation import (
+    load_gdino_model,
+    load_sam_predictor,
+)
+from snowleopard_reid.visualization import (
+    draw_keypoints_overlay,
+    draw_matched_keypoints,
+    draw_side_by_side_comparison,
+)
+from snowleopard_reid.cache import (
+    filter_cached_matches,
+    generate_visualizations_from_npz,
+    is_cached,
+    load_cached_results,
+)
+from snowleopard_reid.data_setup import ensure_data_extracted
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+# Configuration (hardcoded for HF Spaces / local dev)
+CATALOG_ROOT = SPACE_ROOT / "data" / "catalog"
+SAM_CHECKPOINT_DIR = SPACE_ROOT / "data" / "models"
+SAM_CHECKPOINT_NAME = "sam_hq_vit_l.pth"
+EXAMPLES_DIR = SPACE_ROOT / "data" / "examples"
+GDINO_MODEL_ID = "IDEA-Research/grounding-dino-base"
+TEXT_PROMPT = "a snow leopard."
+TOP_K_DEFAULT = 5
+SAM_MODEL_TYPE = "vit_l"
+
+
+@dataclass
+class AppConfig:
+    """Configuration for the Snow Leopard ID UI application."""
+
+    model_path: Path | None
+    catalog_root: Path
+    examples_dir: Path
+    top_k: int
+    port: int
+    share: bool
+    # GDINO+SAM parameters
+    sam_checkpoint_path: Path
+    sam_model_type: str
+    gdino_model_id: str
+    text_prompt: str
+
+
+def ensure_sam_model() -> Path:
+    """Download SAM HQ model if not present.
+
+    Returns:
+        Path to the SAM HQ checkpoint file
+    """
+    sam_path = SAM_CHECKPOINT_DIR / SAM_CHECKPOINT_NAME
+    if not sam_path.exists():
+        logger.info("Downloading SAM HQ model (1.6GB)...")
+        SAM_CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+        hf_hub_download(
+            repo_id="lkeab/hq-sam",
+            filename=SAM_CHECKPOINT_NAME,
+            local_dir=SAM_CHECKPOINT_DIR,
+        )
+        logger.info("SAM HQ model downloaded successfully")
+    return sam_path
+
+
+def get_available_extractors(catalog_root: Path) -> list[str]:
+    """Get list of available feature extractors from catalog.
+
+    Args:
+        catalog_root: Root directory of the leopard catalog
+
+    Returns:
+        List of available extractor names (e.g., ['sift', 'superpoint'])
+    """
+    try:
+        catalog_index = load_catalog_index(catalog_root)
+        extractors = list(catalog_index.get("feature_extractors", {}).keys())
+        if not extractors:
+            logger.warning(f"No extractors found in catalog at {catalog_root}")
+            return ["sift"]  # Default fallback
+        return extractors
+    except Exception as e:
+        logger.error(f"Failed to load catalog index: {e}")
+        return ["sift"]  # Default fallback
+
+
+# Global state for models and catalog (loaded at startup)
+LOADED_MODELS = {}
+
+
+def load_catalog_data(config: AppConfig):
+    """Load catalog index and individual leopard metadata.
+
+    Args:
+        config: Application configuration containing catalog_root
+
+    Returns:
+        Tuple of (catalog_index, individuals_data)
+    """
+    catalog_index_path = config.catalog_root / "catalog_index.yaml"
+
+    # Load catalog index
+    with open(catalog_index_path) as f:
+        catalog_index = yaml.safe_load(f)
+
+    # Load metadata for each individual
+    individuals_data = []
+    for individual in catalog_index["individuals"]:
+        metadata_path = config.catalog_root / individual["metadata_path"]
+        with open(metadata_path) as f:
+            leopard_metadata = yaml.safe_load(f)
+        individuals_data.append(leopard_metadata)
+
+    return catalog_index, individuals_data
+
+
+def initialize_models(config: AppConfig):
+    """Load models at startup for faster inference.
+
+    Args:
+        config: Application configuration containing model paths
+    """
+    logger.info("Initializing models...")
+
+    # Check for GPU
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    logger.info(f"Using device: {device}")
+
+    if device == "cuda":
+        gpu_name = torch.cuda.get_device_name(0)
+        gpu_memory = torch.cuda.get_device_properties(0).total_memory / (1024**3)
+        logger.info(f"GPU: {gpu_name} ({gpu_memory:.1f} GB)")
+
+    # Load Grounding DINO model
+    logger.info(f"Loading Grounding DINO model: {config.gdino_model_id}")
+    gdino_processor, gdino_model = load_gdino_model(
+        model_id=config.gdino_model_id,
+        device=device,
+    )
+    LOADED_MODELS["gdino_processor"] = gdino_processor
+    LOADED_MODELS["gdino_model"] = gdino_model
+    logger.info("Grounding DINO model loaded successfully")
+
+    # Load SAM HQ model
+    logger.info(
+        f"Loading SAM HQ model from {config.sam_checkpoint_path} (type: {config.sam_model_type})"
+    )
+    sam_predictor = load_sam_predictor(
+        checkpoint_path=config.sam_checkpoint_path,
+        model_type=config.sam_model_type,
+        device=device,
+    )
+    LOADED_MODELS["sam_predictor"] = sam_predictor
+    logger.info("SAM HQ model loaded successfully")
+
+    # Store device info and catalog root for callbacks
+    LOADED_MODELS["device"] = device
+    LOADED_MODELS["catalog_root"] = config.catalog_root
+    LOADED_MODELS["text_prompt"] = config.text_prompt
+
+    logger.info("Models initialized successfully")
+
+
+def _load_from_cache(
+    example_path: str,
+    extractor: str,
+    config: "AppConfig",
+    filter_locations: list[str] | None = None,
+    filter_body_parts: list[str] | None = None,
+    top_k: int = 5,
+):
+    """Load cached pipeline results with optional filtering and return UI component updates.
+
+    Supports the v2.0 cache format which stores ALL matches with location/body_part
+    metadata, enabling client-side filtering without re-running the pipeline.
+
+    Args:
+        example_path: Path to the example image
+        extractor: Feature extractor name
+        config: Application configuration
+        filter_locations: Optional list of locations to filter by
+        filter_body_parts: Optional list of body parts to filter by
+        top_k: Number of top matches to return after filtering
+
+    Returns:
+        Tuple of 23 UI components matching run_identification output
+    """
+    # Load cached results
+    cached = load_cached_results(example_path, extractor)
+    predictions = cached["predictions"]
+
+    # Support both v1.0 ("matches") and v2.0 ("all_matches") cache formats
+    if "all_matches" in predictions:
+        all_matches = predictions["all_matches"]
+    else:
+        # Fallback for v1.0 cache format (no filtering support)
+        all_matches = predictions.get("matches", [])
+
+    # Filter and re-rank matches
+    matches = filter_cached_matches(
+        all_matches=all_matches,
+        filter_locations=filter_locations,
+        filter_body_parts=filter_body_parts,
+        top_k=top_k,
+    )
+
+    if not matches:
+        # No matches after filtering - return empty results
+        return (
+            "No matches found with the selected filters",
+            cached["segmentation_image"],
+            cached["cropped_image"],
+            cached["keypoints_image"],
+            [],
+            gr.update(value=None),
+            gr.update(value=None),
+            gr.update(value=""),
+            gr.update(value=""),
+            gr.update(value=""),
+            gr.update(value=""),
+            gr.update(value=""),
+            gr.update(value=""),
+            gr.update(visible=False),
+            gr.update(visible=False),
+            gr.update(visible=False),
+            gr.update(visible=False),
+            gr.update(visible=False),
+            gr.update(value=[]),
+            gr.update(value=[]),
+            gr.update(value=[]),
+            gr.update(value=[]),
+            gr.update(value=[]),
+        )
+
+    # Generate visualizations on-demand from NPZ data
+    logger.info(f"Generating visualizations for {len(matches)} filtered matches...")
+    match_visualizations, clean_comparison_visualizations = (
+        generate_visualizations_from_npz(
+            pairwise_dir=cached["pairwise_dir"],
+            matches=matches,
+            cropped_image_path=cached["pairwise_dir"].parent / "cropped.png",
+        )
+    )
+
+    # Store in global state for match selection
+    LOADED_MODELS["current_match_visualizations"] = match_visualizations
+    LOADED_MODELS["current_clean_comparison_visualizations"] = (
+        clean_comparison_visualizations
+    )
+    LOADED_MODELS["current_enriched_matches"] = matches
+    LOADED_MODELS["current_filter_body_parts"] = filter_body_parts
+    LOADED_MODELS["current_temp_dir"] = None  # No temp dir for cached results
+
+    # Top match info for result text
+    top_match = matches[0]
+    top_leopard_name = top_match["leopard_name"]
+    top_wasserstein = top_match["wasserstein"]
+
+    # Determine confidence level
+    if top_wasserstein >= 0.12:
+        confidence_indicator = "🔵"  # Excellent
+    elif top_wasserstein >= 0.07:
+        confidence_indicator = "🟢"  # Good
+    elif top_wasserstein >= 0.04:
+        confidence_indicator = "🟡"  # Fair
+    else:
+        confidence_indicator = "🔴"  # Uncertain
+
+    result_text = f"## {confidence_indicator} {top_leopard_name.title()}"
+
+    # Build dataset for top-K matches table
+    dataset_samples = []
+    for match in matches:
+        rank = match["rank"]
+        leopard_name = match["leopard_name"]
+        wasserstein = match["wasserstein"]
+
+        # Use location from cache (v2.0) or extract from path
+        location = match.get("location", "unknown")
+        if location == "unknown":
+            catalog_id = match["catalog_id"]
+            catalog_metadata = get_catalog_metadata_for_id(
+                config.catalog_root, catalog_id
+            )
+            if catalog_metadata:
+                img_path_parts = Path(catalog_metadata["image_path"]).parts
+                try:
+                    db_idx = img_path_parts.index("database")
+                    if db_idx + 1 < len(img_path_parts):
+                        location = img_path_parts[db_idx + 1]
+                except ValueError:
+                    pass
+
+        # Confidence indicator
+        if wasserstein >= 0.12:
+            indicator = "🔵"
+        elif wasserstein >= 0.07:
+            indicator = "🟢"
+        elif wasserstein >= 0.04:
+            indicator = "🟡"
+        else:
+            indicator = "🔴"
+
+        dataset_samples.append(
+            [
+                rank,
+                indicator,
+                leopard_name.title(),
+                location.replace("_", " ").title(),
+                f"{wasserstein:.4f}",
+            ]
+        )
+
+    # Load rank 1 details
+    rank1_details = load_match_details_for_rank(rank=1)
+
+    # Return all 23 outputs
+    return (
+        result_text,  # 1. Top match result text
+        cached["segmentation_image"],  # 2. Segmentation overlay
+        cached["cropped_image"],  # 3. Cropped leopard
+        cached["keypoints_image"],  # 4. Extracted keypoints
+        dataset_samples,  # 5. Matches table data
+        *rank1_details,  # 6-23. visualizations, header, indicators, galleries
+    )
+
+
+def run_identification(
+    image,
+    extractor: str,
+    top_k: int,
+    selected_locations: list[str],
+    selected_body_parts: list[str],
+    example_path: str | None,
+    config: AppConfig,
+):
+    """Run snow leopard identification pipeline on uploaded image.
+
+    Args:
+        image: PIL Image from Gradio upload
+        extractor: Feature extractor to use ('sift', 'superpoint', 'disk', 'aliked')
+        top_k: Number of top matches to return
+        selected_locations: List of selected locations (includes "all" for no filtering)
+        selected_body_parts: List of selected body parts (includes "all" for no filtering)
+        example_path: Path to example image if selected from examples (for cache lookup)
+        config: Application configuration
+
+    Returns:
+        Tuple of UI components to update
+    """
+    if image is None:
+        # Return 23 empty outputs (5 pipeline + 18 rank 1 details)
+        return (
+            "Please upload an image first",  # 1. result_text
+            None,  # 2. seg_viz
+            None,  # 3. cropped_image
+            None,  # 4. extracted_kpts_viz
+            [],  # 5. dataset_samples
+            gr.update(value=None),  # 6. matched_kpts_viz
+            gr.update(value=None),  # 7. clean_comparison_viz
+            gr.update(value=""),  # 8. header
+            gr.update(value=""),  # 9. head indicator
+            gr.update(value=""),  # 10. left_flank indicator
+            gr.update(value=""),  # 11. right_flank indicator
+            gr.update(value=""),  # 12. tail indicator
+            gr.update(value=""),  # 13. misc indicator
+            gr.update(visible=False),  # 14. head empty message
+            gr.update(visible=False),  # 15. left_flank empty message
+            gr.update(visible=False),  # 16. right_flank empty message
+            gr.update(visible=False),  # 17. tail empty message
+            gr.update(visible=False),  # 18. misc empty message
+            gr.update(value=[]),  # 19. head gallery
+            gr.update(value=[]),  # 20. left_flank gallery
+            gr.update(value=[]),  # 21. right_flank gallery
+            gr.update(value=[]),  # 22. tail gallery
+            gr.update(value=[]),  # 23. misc gallery
+        )
+
+    # Convert filter selections to None if "all" is selected
+    filter_locations = (
+        None
+        if not selected_locations or "all" in selected_locations
+        else selected_locations
+    )
+    filter_body_parts_parsed = (
+        None
+        if not selected_body_parts or "all" in selected_body_parts
+        else selected_body_parts
+    )
+
+    # Check cache for example images (v2.0 cache supports filtering)
+    if example_path and is_cached(example_path, extractor):
+        logger.info(f"Cache hit for {example_path} with {extractor}")
+        if filter_locations or filter_body_parts_parsed:
+            logger.info(f"  Applying filters: locations={filter_locations}, body_parts={filter_body_parts_parsed}")
+        try:
+            return _load_from_cache(
+                example_path,
+                extractor,
+                config,
+                filter_locations=filter_locations,
+                filter_body_parts=filter_body_parts_parsed,
+                top_k=int(top_k),
+            )
+        except Exception as e:
+            logger.warning(f"Cache load failed, running pipeline: {e}")
+            # Fall through to run full pipeline
+
+    # Use the already-parsed filter values for the pipeline
+    filter_body_parts = filter_body_parts_parsed
+
+    # Log applied filters
+    if filter_locations or filter_body_parts:
+        filter_desc = []
+        if filter_locations:
+            filter_desc.append(f"locations: {', '.join(filter_locations)}")
+        if filter_body_parts:
+            filter_desc.append(f"body parts: {', '.join(filter_body_parts)}")
+        logger.info(f"Applied filters - {' | '.join(filter_desc)}")
+    else:
+        logger.info("No filters applied - matching against entire catalog")
+
+    try:
+        # Create temporary directory for this query
+        temp_dir = Path(tempfile.mkdtemp(prefix="snowleopard_id_"))
+        temp_image_path = temp_dir / "query.jpg"
+
+        # Save uploaded image
+        logger.info(f"Image type: {type(image)}")
+        logger.info(f"Image mode: {image.mode if hasattr(image, 'mode') else 'N/A'}")
+        logger.info(f"Image size: {image.size if hasattr(image, 'size') else 'N/A'}")
+        image.save(temp_image_path, quality=95)
+
+        # Verify saved image
+        saved_size = temp_image_path.stat().st_size
+        logger.info(f"Saved image size: {saved_size / 1024 / 1024:.2f} MB")
+
+        logger.info(f"Processing query image: {temp_image_path}")
+
+        device = LOADED_MODELS.get("device", "cpu")
+
+        # Step 1: Run GDINO+SAM segmentation using pre-loaded models
+        logger.info("Running GDINO+SAM segmentation...")
+        gdino_processor = LOADED_MODELS.get("gdino_processor")
+        gdino_model = LOADED_MODELS.get("gdino_model")
+        sam_predictor = LOADED_MODELS.get("sam_predictor")
+        text_prompt = LOADED_MODELS.get("text_prompt", "a snow leopard.")
+
+        seg_stage = run_segmentation_stage(
+            image_path=temp_image_path,
+            strategy="gdino_sam",
+            confidence_threshold=0.2,
+            device=device,
+            gdino_processor=gdino_processor,
+            gdino_model=gdino_model,
+            sam_predictor=sam_predictor,
+            text_prompt=text_prompt,
+            box_threshold=0.30,
+            text_threshold=0.20,
+        )
+
+        predictions = seg_stage["data"]["predictions"]
+        logger.info(f"Number of predictions: {len(predictions)}")
+
+        if not predictions:
+            logger.warning("No predictions found from segmentation")
+            logger.warning(f"Full segmentation stage: {seg_stage}")
+            # Return 23 empty outputs (5 pipeline + 18 rank 1 details)
+            return (
+                "No snow leopards detected in image",  # 1. result_text
+                None,  # 2. seg_viz
+                None,  # 3. cropped_image
+                None,  # 4. extracted_kpts_viz
+                [],  # 5. dataset_samples
+                gr.update(value=None),  # 6. matched_kpts_viz
+                gr.update(value=None),  # 7. clean_comparison_viz
+                gr.update(value=""),  # 8. header
+                gr.update(value=""),  # 9. head indicator
+                gr.update(value=""),  # 10. left_flank indicator
+                gr.update(value=""),  # 11. right_flank indicator
+                gr.update(value=""),  # 12. tail indicator
+                gr.update(value=""),  # 13. misc indicator
+                gr.update(visible=False),  # 14. head empty message
+                gr.update(visible=False),  # 15. left_flank empty message
+                gr.update(visible=False),  # 16. right_flank empty message
+                gr.update(visible=False),  # 17. tail empty message
+                gr.update(visible=False),  # 18. misc empty message
+                gr.update(value=[]),  # 19. head gallery
+                gr.update(value=[]),  # 20. left_flank gallery
+                gr.update(value=[]),  # 21. right_flank gallery
+                gr.update(value=[]),  # 22. tail gallery
+                gr.update(value=[]),  # 23. misc gallery
+            )
+
+        # Step 2: Select best mask
+        logger.info("Selecting best mask...")
+        selected_idx, selected_pred = select_best_mask(
+            predictions,
+            strategy="confidence_area",
+        )
+
+        # Step 3: Preprocess (crop and mask)
+        logger.info("Preprocessing query image...")
+        prep_stage = run_preprocess_stage(
+            image_path=temp_image_path,
+            mask=selected_pred["mask"],
+            padding=5,
+        )
+
+        cropped_image_pil = prep_stage["data"]["cropped_image"]
+
+        # Save cropped image for visualization later
+        cropped_path = temp_dir / "cropped.jpg"
+        cropped_image_pil.save(cropped_path)
+
+        # Step 4: Extract features
+        logger.info(f"Extracting features using {extractor.upper()}...")
+        feat_stage = run_feature_extraction_stage(
+            image=cropped_image_pil,
+            extractor=extractor,
+            max_keypoints=2048,
+            device=device,
+        )
+
+        query_features = feat_stage["data"]["features"]
+
+        # Step 5: Match against catalog
+        logger.info("Matching against catalog...")
+        pairwise_dir = temp_dir / "pairwise"
+        pairwise_dir.mkdir(exist_ok=True)
+
+        match_stage = run_matching_stage(
+            query_features=query_features,
+            catalog_path=config.catalog_root,
+            top_k=top_k,
+            extractor=extractor,
+            device=device,
+            query_image_path=str(cropped_path),
+            pairwise_output_dir=pairwise_dir,
+            filter_locations=filter_locations,
+            filter_body_parts=filter_body_parts,
+        )
+
+        matches = match_stage["data"]["matches"]
+
+        if not matches:
+            # Return 23 empty outputs (5 pipeline + 18 rank 1 details)
+            return (
+                "No matches found in catalog",  # 1. result_text
+                None,  # 2. seg_viz
+                cropped_image_pil,  # 3. cropped_image
+                None,  # 4. extracted_kpts_viz
+                [],  # 5. dataset_samples
+                gr.update(value=None),  # 6. matched_kpts_viz
+                gr.update(value=None),  # 7. clean_comparison_viz
+                gr.update(value=""),  # 8. header
+                gr.update(value=""),  # 9. head indicator
+                gr.update(value=""),  # 10. left_flank indicator
+                gr.update(value=""),  # 11. right_flank indicator
+                gr.update(value=""),  # 12. tail indicator
+                gr.update(value=""),  # 13. misc indicator
+                gr.update(visible=False),  # 14. head empty message
+                gr.update(visible=False),  # 15. left_flank empty message
+                gr.update(visible=False),  # 16. right_flank empty message
+                gr.update(visible=False),  # 17. tail empty message
+                gr.update(visible=False),  # 18. misc empty message
+                gr.update(value=[]),  # 19. head gallery
+                gr.update(value=[]),  # 20. left_flank gallery
+                gr.update(value=[]),  # 21. right_flank gallery
+                gr.update(value=[]),  # 22. tail gallery
+                gr.update(value=[]),  # 23. misc gallery
+            )
+
+        # Top match
+        top_match = matches[0]
+        top_leopard_name = top_match["leopard_name"]
+        top_wasserstein = top_match["wasserstein"]
+
+        # Determine confidence level (higher Wasserstein = better match)
+        if top_wasserstein >= 0.12:
+            confidence_indicator = "🔵"  # Excellent
+        elif top_wasserstein >= 0.07:
+            confidence_indicator = "🟢"  # Good
+        elif top_wasserstein >= 0.04:
+            confidence_indicator = "🟡"  # Fair
+        else:
+            confidence_indicator = "🔴"  # Uncertain
+
+        result_text = f"## {confidence_indicator} {top_leopard_name.title()}"
+
+        # Create segmentation visualization
+        seg_viz = create_segmentation_viz(
+            image_path=temp_image_path, mask=selected_pred["mask"]
+        )
+
+        # Generate extracted keypoints visualization
+        extracted_kpts_viz = None
+        try:
+            # Extract keypoints from query features for visualization
+            query_kpts = query_features["keypoints"].cpu().numpy()
+            extracted_kpts_viz = draw_keypoints_overlay(
+                image_path=cropped_path,
+                keypoints=query_kpts,
+                max_keypoints=500,
+                color="blue",
+                ps=10,
+            )
+        except Exception as e:
+            logger.error(f"Error creating extracted keypoints visualization: {e}")
+
+        # Build dataset for top-K matches table
+        dataset_samples = []
+        match_visualizations = {}
+        clean_comparison_visualizations = {}
+
+        for match in matches:
+            rank = match["rank"]
+            leopard_name = match["leopard_name"]
+            wasserstein = match["wasserstein"]
+            catalog_img_path = Path(match["filepath"])
+
+            # Get location from catalog metadata
+            catalog_id = match["catalog_id"]
+            catalog_metadata = get_catalog_metadata_for_id(
+                config.catalog_root, catalog_id
+            )
+            location = "unknown"
+            if catalog_metadata:
+                # Extract location from path: database/{location}/{individual}/...
+                img_path_parts = Path(catalog_metadata["image_path"]).parts
+                if len(img_path_parts) >= 3:
+                    # Find 'database' in path and get next part
+                    try:
+                        db_idx = img_path_parts.index("database")
+                        if db_idx + 1 < len(img_path_parts):
+                            location = img_path_parts[db_idx + 1]
+                    except ValueError:
+                        pass
+
+            # Confidence indicator (higher Wasserstein = better match)
+            if wasserstein >= 0.12:
+                indicator = "🔵"  # Excellent
+            elif wasserstein >= 0.07:
+                indicator = "🟢"  # Good
+            elif wasserstein >= 0.04:
+                indicator = "🟡"  # Fair
+            else:
+                indicator = "🔴"  # Uncertain
+
+            # Create visualizations for this match
+            npz_path = pairwise_dir / f"rank_{rank:02d}_{match['catalog_id']}.npz"
+            if npz_path.exists():
+                try:
+                    pairwise_data = np.load(npz_path)
+
+                    # Create matched keypoints visualization
+                    match_viz = draw_matched_keypoints(
+                        query_image_path=cropped_path,
+                        catalog_image_path=catalog_img_path,
+                        query_keypoints=pairwise_data["query_keypoints"],
+                        catalog_keypoints=pairwise_data["catalog_keypoints"],
+                        match_scores=pairwise_data["match_scores"],
+                        max_matches=100,
+                    )
+                    match_visualizations[rank] = match_viz
+
+                    # Create clean comparison visualization
+                    clean_viz = draw_side_by_side_comparison(
+                        query_image_path=cropped_path,
+                        catalog_image_path=catalog_img_path,
+                    )
+                    clean_comparison_visualizations[rank] = clean_viz
+                except Exception as e:
+                    logger.error(f"Error creating visualizations for rank {rank}: {e}")
+
+            # Format for table (as list, not dict)
+            dataset_samples.append(
+                [
+                    rank,
+                    indicator,
+                    leopard_name.title(),
+                    location.replace("_", " ").title(),
+                    f"{wasserstein:.4f}",
+                ]
+            )
+
+        # Store match visualizations, enriched matches, filters, and temp_dir in global state
+        LOADED_MODELS["current_match_visualizations"] = match_visualizations
+        LOADED_MODELS["current_clean_comparison_visualizations"] = (
+            clean_comparison_visualizations
+        )
+        LOADED_MODELS["current_enriched_matches"] = matches
+        LOADED_MODELS["current_filter_body_parts"] = filter_body_parts
+        LOADED_MODELS["current_temp_dir"] = temp_dir
+
+        # Automatically load rank 1 details (visualizations + galleries)
+        rank1_details = load_match_details_for_rank(rank=1)
+
+        # Return 23 outputs total:
+        # - 5 pipeline outputs (result_text, seg_viz, cropped_image, extracted_kpts_viz, dataset_samples)
+        # - 18 rank 1 details (from load_match_details_for_rank)
+        return (
+            result_text,  # 1. Top match result text
+            seg_viz,  # 2. Segmentation overlay
+            cropped_image_pil,  # 3. Cropped leopard
+            extracted_kpts_viz,  # 4. Extracted keypoints
+            dataset_samples,  # 5. Matches table data
+            # Unpack all 18 rank 1 details:
+            *rank1_details,  # 6-23. visualizations, header, indicators, galleries
+        )
+
+    except Exception as e:
+        logger.error(f"Error processing image: {e}", exc_info=True)
+        # Return 23 empty outputs (5 pipeline + 18 rank 1 details)
+        return (
+            f"Error processing image: {str(e)}",  # 1. result_text
+            None,  # 2. seg_viz
+            None,  # 3. cropped_image
+            None,  # 4. extracted_kpts_viz
+            [],  # 5. dataset_samples
+            gr.update(value=None),  # 6. matched_kpts_viz
+            gr.update(value=None),  # 7. clean_comparison_viz
+            gr.update(value=""),  # 8. header
+            gr.update(value=""),  # 9. head indicator
+            gr.update(value=""),  # 10. left_flank indicator
+            gr.update(value=""),  # 11. right_flank indicator
+            gr.update(value=""),  # 12. tail indicator
+            gr.update(value=""),  # 13. misc indicator
+            gr.update(visible=False),  # 14. head empty message
+            gr.update(visible=False),  # 15. left_flank empty message
+            gr.update(visible=False),  # 16. right_flank empty message
+            gr.update(visible=False),  # 17. tail empty message
+            gr.update(visible=False),  # 18. misc empty message
+            gr.update(value=[]),  # 19. head gallery
+            gr.update(value=[]),  # 20. left_flank gallery
+            gr.update(value=[]),  # 21. right_flank gallery
+            gr.update(value=[]),  # 22. tail gallery
+            gr.update(value=[]),  # 23. misc gallery
+        )
+
+
+def create_segmentation_viz(image_path, mask):
+    """Create visualization of segmentation mask overlaid on image."""
+    # Load original image
+    img = cv2.imread(str(image_path))
+    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+
+    # Resize mask to match image dimensions if needed
+    if mask.shape[:2] != img_rgb.shape[:2]:
+        mask_resized = cv2.resize(
+            mask.astype(np.uint8),
+            (img_rgb.shape[1], img_rgb.shape[0]),
+            interpolation=cv2.INTER_NEAREST,
+        )
+    else:
+        mask_resized = mask
+
+    # Create colored overlay
+    overlay = img_rgb.copy()
+    overlay[mask_resized > 0] = [255, 0, 0]  # Red for masked region
+
+    # Blend
+    alpha = 0.4
+    blended = cv2.addWeighted(img_rgb, 1 - alpha, overlay, alpha, 0)
+
+    return Image.fromarray(blended)
+
+
+def load_match_details_for_rank(rank: int) -> tuple:
+    """Load all match details (visualizations + galleries) for a specific rank.
+
+    This is a reusable helper function that encapsulates the logic for loading
+    match visualizations, galleries, and metadata for a given rank. Used by both
+    the automatic rank 1 display after pipeline completion and the interactive
+    row selection handler.
+
+    Args:
+        rank: The rank to load (1-indexed)
+
+    Returns:
+        Tuple of 18 Gradio component updates:
+        (matched_kpts_viz, clean_comparison_viz, header,
+         head_indicator, left_flank_indicator, right_flank_indicator, tail_indicator, misc_indicator,
+         head_empty_message, left_flank_empty_message, right_flank_empty_message,
+         tail_empty_message, misc_empty_message,
+         gallery_head, gallery_left_flank, gallery_right_flank, gallery_tail, gallery_misc)
+    """
+    # Get stored data from global state
+    match_visualizations = LOADED_MODELS.get("current_match_visualizations", {})
+    clean_comparison_visualizations = LOADED_MODELS.get(
+        "current_clean_comparison_visualizations", {}
+    )
+    enriched_matches = LOADED_MODELS.get("current_enriched_matches", [])
+    filter_body_parts = LOADED_MODELS.get("current_filter_body_parts")
+    catalog_root = LOADED_MODELS.get("catalog_root")
+
+    # Find the match for the requested rank
+    selected_match = None
+    for match in enriched_matches:
+        if match["rank"] == rank:
+            selected_match = match
+            break
+
+    if not selected_match or rank not in match_visualizations:
+        # Return empty updates for all 18 outputs
+        return (
+            gr.update(value=None),  # 1. matched_kpts_viz
+            gr.update(value=None),  # 2. clean_comparison_viz
+            gr.update(value=""),  # 3. header
+            gr.update(value=""),  # 4. head indicator
+            gr.update(value=""),  # 5. left_flank indicator
+            gr.update(value=""),  # 6. right_flank indicator
+            gr.update(value=""),  # 7. tail indicator
+            gr.update(value=""),  # 8. misc indicator
+            gr.update(visible=False),  # 9. head empty message
+            gr.update(visible=False),  # 10. left_flank empty message
+            gr.update(visible=False),  # 11. right_flank empty message
+            gr.update(visible=False),  # 12. tail empty message
+            gr.update(visible=False),  # 13. misc empty message
+            gr.update(value=[]),  # 14. head gallery
+            gr.update(value=[]),  # 15. left_flank gallery
+            gr.update(value=[]),  # 16. right_flank gallery
+            gr.update(value=[]),  # 17. tail gallery
+            gr.update(value=[]),  # 18. misc gallery
+        )
+
+    # Get both visualizations
+    match_viz = match_visualizations[rank]
+    clean_viz = clean_comparison_visualizations.get(rank)
+
+    # Create dynamic header with leopard name
+    leopard_name = selected_match["leopard_name"]
+    header_text = f"## Reference Images for {leopard_name.title()}"
+
+    # Load galleries organized by body part
+    galleries = {}
+    if catalog_root:
+        try:
+            # Extract location from match filepath
+            location = None
+            filepath = Path(selected_match["filepath"])
+            parts = filepath.parts
+            if "database" in parts:
+                db_idx = parts.index("database")
+                if db_idx + 1 < len(parts):
+                    location = parts[db_idx + 1]
+
+            galleries = load_matched_individual_gallery_by_body_part(
+                catalog_root=catalog_root,
+                leopard_name=leopard_name,
+                location=location,
+            )
+        except Exception as e:
+            logger.error(f"Error loading gallery for {leopard_name}: {e}")
+            # Initialize empty galleries on error
+            galleries = {
+                "head": [],
+                "left_flank": [],
+                "right_flank": [],
+                "tail": [],
+                "misc": [],
+            }
+
+    # Create emoji indicators for filtered body parts
+    def get_indicator(body_part: str) -> str:
+        """Return star if body part was in filter, empty string otherwise."""
+        if filter_body_parts and body_part in filter_body_parts:
+            return "* (filtered)"
+        return ""
+
+    # Helper to determine if empty message should be visible
+    def is_empty(body_part: str) -> bool:
+        """Return True if no images for this body part."""
+        return len(galleries.get(body_part, [])) == 0
+
+    return (
+        gr.update(value=match_viz),  # 1. matched_kpts_viz
+        gr.update(value=clean_viz),  # 2. clean_comparison_viz
+        gr.update(value=header_text),  # 3. header
+        gr.update(value=get_indicator("head")),  # 4. head indicator
+        gr.update(value=get_indicator("left_flank")),  # 5. left_flank indicator
+        gr.update(value=get_indicator("right_flank")),  # 6. right_flank indicator
+        gr.update(value=get_indicator("tail")),  # 7. tail indicator
+        gr.update(value=get_indicator("misc")),  # 8. misc indicator
+        gr.update(visible=is_empty("head")),  # 9. head empty message
+        gr.update(visible=is_empty("left_flank")),  # 10. left_flank empty message
+        gr.update(visible=is_empty("right_flank")),  # 11. right_flank empty message
+        gr.update(visible=is_empty("tail")),  # 12. tail empty message
+        gr.update(visible=is_empty("misc")),  # 13. misc empty message
+        gr.update(
+            value=galleries.get("head", []), visible=not is_empty("head")
+        ),  # 14. head gallery
+        gr.update(
+            value=galleries.get("left_flank", []), visible=not is_empty("left_flank")
+        ),  # 15. left_flank gallery
+        gr.update(
+            value=galleries.get("right_flank", []), visible=not is_empty("right_flank")
+        ),  # 16. right_flank gallery
+        gr.update(
+            value=galleries.get("tail", []), visible=not is_empty("tail")
+        ),  # 17. tail gallery
+        gr.update(
+            value=galleries.get("misc", []), visible=not is_empty("misc")
+        ),  # 18. misc gallery
+    )
+
+
+def on_match_selected(evt: gr.SelectData):
+    """Handle selection of a match from the dataset table.
+
+    Returns both visualizations, header, indicators, empty messages,
+    and galleries organized by body part.
+    """
+    # evt.index is [row, col] for Dataframe, we want row
+    if isinstance(evt.index, (list, tuple)):
+        selected_row = evt.index[0]
+    else:
+        selected_row = evt.index
+
+    selected_rank = selected_row + 1  # Ranks are 1-indexed
+
+    # Delegate to the reusable helper function
+    return load_match_details_for_rank(selected_rank)
+
+
+def load_matched_individual_gallery_by_body_part(
+    catalog_root: Path,
+    leopard_name: str,
+    location: str | None = None,
+) -> dict[str, list[tuple]]:
+    """Load all images for a matched individual organized by body part.
+
+    Args:
+        catalog_root: Path to catalog root directory
+        leopard_name: Name of the matched individual (e.g., "karindas")
+        location: Geographic location (e.g., "skycrest_valley")
+
+    Returns:
+        Dict mapping body part to list of (PIL.Image, caption) tuples:
+        {
+            "head": [(img1, caption1), (img2, caption2), ...],
+            "left_flank": [...],
+            "right_flank": [...],
+            "tail": [...],
+            "misc": [...]
+        }
+    """
+    # Initialize dict with all body parts
+    galleries = {
+        "head": [],
+        "left_flank": [],
+        "right_flank": [],
+        "tail": [],
+        "misc": [],
+    }
+
+    # Find metadata path: database/{location}/{individual}/metadata.yaml
+    if location:
+        metadata_path = (
+            catalog_root / "database" / location / leopard_name / "metadata.yaml"
+        )
+    else:
+        # Try to find the individual in any location
+        metadata_path = None
+        database_dir = catalog_root / "database"
+        if database_dir.exists():
+            for loc_dir in database_dir.iterdir():
+                if loc_dir.is_dir():
+                    potential_path = loc_dir / leopard_name / "metadata.yaml"
+                    if potential_path.exists():
+                        metadata_path = potential_path
+                        break
+
+    if not metadata_path or not metadata_path.exists():
+        logger.warning(f"Metadata not found for {leopard_name}")
+        return galleries
+
+    try:
+        metadata = load_leopard_metadata(metadata_path)
+
+        # Load all images organized by body part
+        for img_entry in metadata["reference_images"]:
+            body_part = img_entry.get("body_part", "misc")
+
+            # Normalize body_part to match our keys
+            if body_part not in galleries:
+                body_part = "misc"  # Default to misc if unknown
+
+            # Load image
+            img_path = catalog_root / "database" / img_entry["path"]
+
+            try:
+                img = Image.open(img_path)
+                # Simple caption: just body part name
+                caption = body_part
+                galleries[body_part].append((img, caption))
+            except Exception as e:
+                logger.error(f"Error loading image {img_path}: {e}")
+
+    except Exception as e:
+        logger.error(f"Error loading metadata for {leopard_name}: {e}")
+
+    return galleries
+
+
+def cleanup_temp_files():
+    """Clean up temporary files from previous run."""
+    temp_dir = LOADED_MODELS.get("current_temp_dir")
+    if temp_dir and temp_dir.exists():
+        try:
+            shutil.rmtree(temp_dir)
+            logger.info(f"Cleaned up temporary directory: {temp_dir}")
+        except Exception as e:
+            logger.warning(f"Error cleaning up temp directory: {e}")
+
+
+def create_leopard_tab(leopard_metadata, config: AppConfig):
+    """Create a tab for displaying a single leopard's images.
+
+    Args:
+        leopard_metadata: Metadata dictionary for the leopard individual
+        config: Application configuration
+    """
+    # Support both 'leopard_name' and 'individual_name' keys
+    leopard_name = leopard_metadata.get("leopard_name") or leopard_metadata.get(
+        "individual_name"
+    )
+    location = leopard_metadata.get("location", "unknown")
+    total_images = leopard_metadata["statistics"]["total_reference_images"]
+
+    # Get body parts from statistics
+    body_parts = leopard_metadata["statistics"].get(
+        "body_parts_represented", leopard_metadata["statistics"].get("body_parts", [])
+    )
+    body_parts_str = ", ".join(body_parts) if body_parts else "N/A"
+
+    with gr.Tab(f"{leopard_name}"):
+        # Header with statistics
+        gr.Markdown(
+            f"### {leopard_name.title()}\n"
+            f"**Location:** {location.replace('_', ' ').title()} | "
+            f"**{total_images} images** | "
+            f"**Body parts:** {body_parts_str}"
+        )
+
+        # Load all images with body_part captions
+        gallery_data = []
+        for img_entry in leopard_metadata["reference_images"]:
+            img_path = config.catalog_root / "database" / img_entry["path"]
+            body_part = img_entry.get("body_part", "unknown")
+            try:
+                img = Image.open(img_path)
+                # Caption format: just body_part (location is already in tab)
+                caption = body_part
+                gallery_data.append((img, caption))
+            except Exception as e:
+                logger.error(f"Error loading image {img_path}: {e}")
+
+        # Display gallery
+        gr.Gallery(
+            value=gallery_data,
+            label=f"Reference Images for {leopard_name.title()}",
+            columns=6,
+            height=700,
+            object_fit="scale-down",
+            allow_preview=True,
+        )
+
+
+def create_app(config: AppConfig):
+    """Create and configure the Gradio application.
+
+    Args:
+        config: Application configuration
+    """
+    # Extract data archives on first run (for HF Spaces deployment)
+    ensure_data_extracted()
+
+    # Initialize models at startup
+    initialize_models(config)
+
+    # Load catalog data
+    catalog_index, individuals_data = load_catalog_data(config)
+
+    # Build example images list from examples directory
+    example_images = (
+        list(config.examples_dir.glob("*.jpg"))
+        + list(config.examples_dir.glob("*.JPG"))
+        + list(config.examples_dir.glob("*.png"))
+    )
+    # Sort with Ayima images last
+    example_images.sort(key=lambda x: (1 if "Ayima" in x.name else 0, x.name))
+
+    # Create interface
+    with gr.Blocks(title="Snow Leopard Identification") as app:
+        # Hidden state to track which example image was selected (for cache lookup)
+        selected_example_state = gr.State(value=None)
+
+        gr.HTML("""
+            <div style="text-align: center; margin-bottom: 20px;">
+                <h1 style="margin-bottom: 10px;">Snow Leopard Identification</h1>
+                <p style="font-size: 16px; color: #666;">
+                    Computer vision system for identifying individual snow leopards.
+                </p>
+            </div>
+        """)
+
+        # Main tabs
+        with gr.Tabs():
+            # Tab 1: Identify Snow Leopard
+            with gr.Tab("Identify Snow Leopard"):
+                gr.Markdown("""
+Upload a snow leopard image or select an example to identify which individual it is.
+The system will detect the leopard, extract distinctive features, and match against the catalog.
+                """)
+
+                with gr.Row():
+                    # Left column: Input
+                    with gr.Column(scale=1):
+                        image_input = gr.Image(
+                            type="pil",
+                            label="Upload Snow Leopard Image",
+                            sources=["upload", "clipboard"],
+                        )
+
+                        examples_component = gr.Examples(
+                            examples=[[str(img)] for img in example_images],
+                            inputs=image_input,
+                            label="Example Images",
+                        )
+
+                        # Track example selection for cache lookup
+                        def on_example_select(evt: gr.SelectData):
+                            """Update state when an example is selected."""
+                            if evt.index is not None:
+                                return str(example_images[evt.index])
+                            return None
+
+                        # When image changes, check if it matches an example
+                        def check_if_example(img):
+                            """Check if uploaded image matches an example path."""
+                            # When user uploads a new image, clear the example state
+                            # Examples component handles setting state via select event
+                            return gr.update()  # No change to state on image change
+
+                        examples_component.dataset.select(
+                            fn=on_example_select,
+                            outputs=[selected_example_state],
+                        )
+
+                        # Clear example state when user uploads a new image
+                        image_input.upload(
+                            fn=lambda: None,
+                            outputs=[selected_example_state],
+                        )
+
+                        # Location filter dropdown
+                        available_locations = get_available_locations(
+                            config.catalog_root
+                        )
+                        location_filter = gr.Dropdown(
+                            choices=available_locations,
+                            value=["all"],
+                            multiselect=True,
+                            label="Filter by Location",
+                            info="Select locations to search (default: all locations)",
+                        )
+
+                        # Body part filter dropdown
+                        available_body_parts = get_available_body_parts(
+                            config.catalog_root
+                        )
+                        body_part_filter = gr.Dropdown(
+                            choices=available_body_parts,
+                            value=["all"],
+                            multiselect=True,
+                            label="Filter by Body Part",
+                            info="Select body parts to match (default: all body parts)",
+                        )
+
+                        # Advanced Configuration Accordion
+                        with gr.Accordion("Advanced Configuration", open=False):
+                            # Feature extractor dropdown
+                            available_extractors = get_available_extractors(
+                                config.catalog_root
+                            )
+                            extractor_dropdown = gr.Dropdown(
+                                choices=available_extractors,
+                                value="sift"
+                                if "sift" in available_extractors
+                                else (
+                                    available_extractors[0]
+                                    if available_extractors
+                                    else "sift"
+                                ),
+                                label="Feature Extractor",
+                                info=f"Available: {', '.join(available_extractors)}",
+                                scale=1,
+                            )
+
+                            # Top-K parameter
+                            top_k_input = gr.Number(
+                                value=config.top_k,
+                                label="Top-K Matches",
+                                info="Number of top matches to return",
+                                minimum=1,
+                                maximum=20,
+                                step=1,
+                                precision=0,
+                                scale=1,
+                            )
+
+                        submit_btn = gr.Button(
+                            value="Identify Snow Leopard",
+                            variant="primary",
+                            size="lg",
+                        )
+
+                    # Right column: Results
+                    with gr.Column(scale=4):
+                        # Top-1 prediction
+                        result_text = gr.Markdown("")
+
+                        # Tabs for different result views
+                        with gr.Tabs():
+                            with gr.Tab("Model Internals"):
+                                gr.Markdown("""
+View the internal processing steps: segmentation mask, cropped leopard, and extracted keypoints.
+                                """)
+                                with gr.Row():
+                                    seg_viz = gr.Image(
+                                        label="Segmentation Overlay",
+                                        type="pil",
+                                    )
+                                    cropped_image = gr.Image(
+                                        label="Extracted Snow Leopard",
+                                        type="pil",
+                                    )
+                                    extracted_kpts_viz = gr.Image(
+                                        label="Extracted Keypoints",
+                                        type="pil",
+                                    )
+
+                            with gr.Tab("Top Matches"):
+                                gr.Markdown("""
+Click a row to view detailed feature matching visualization and all reference images for that leopard.
+
+**Higher Wasserstein distance = better match** (typical range: 0.04-0.27)
+
+**Confidence Levels:** 🔵 Excellent (>=0.12) | 🟢 Good (>=0.07) | 🟡 Fair (>=0.04) | 🔴 Uncertain (<0.04)
+                                """)
+
+                                matches_dataset = gr.Dataframe(
+                                    headers=[
+                                        "Rank",
+                                        "Confidence",
+                                        "Leopard Name",
+                                        "Location",
+                                        "Wasserstein",
+                                    ],
+                                    label="Top Matches",
+                                    wrap=True,
+                                    col_count=(5, "fixed"),
+                                )
+
+                                # Visualization container (always visible, images populated on pipeline completion)
+                                with gr.Column() as viz_tabs:
+                                    # Tabbed visualization views
+                                    with gr.Tabs():
+                                        with gr.Tab("Matched Keypoints"):
+                                            gr.Markdown(
+                                                "Feature matching with keypoints and confidence-coded connecting lines. "
+                                                "**Green** = high confidence, **Yellow** = medium, **Red** = low."
+                                            )
+                                            matched_kpts_viz = gr.Image(
+                                                type="pil",
+                                                show_label=False,
+                                            )
+
+                                        with gr.Tab("Clean Comparison"):
+                                            gr.Markdown(
+                                                "Side-by-side comparison without feature annotations. "
+                                                "Useful for assessing overall visual similarity and spotting patterns."
+                                            )
+                                            clean_comparison_viz = gr.Image(
+                                                type="pil",
+                                                show_label=False,
+                                            )
+
+                                    # Dynamic header showing matched leopard name
+                                    selected_match_header = gr.Markdown("", visible=True)
+
+                                    # Create tabs for each body part
+                                    with gr.Tabs():
+                                        with gr.Tab("Head"):
+                                            head_indicator = gr.Markdown("")
+                                            head_empty_message = gr.Markdown(
+                                                value='<div style="text-align: center; padding: 60px 20px; color: #888;">'
+                                                '<p style="font-size: 16px;">No reference images available for this body part</p>'
+                                                "</div>",
+                                                visible=False,
+                                            )
+                                            gallery_head = gr.Gallery(
+                                                columns=6,
+                                                height=400,
+                                                object_fit="scale-down",
+                                                allow_preview=True,
+                                            )
+
+                                        with gr.Tab("Left Flank"):
+                                            left_flank_indicator = gr.Markdown("")
+                                            left_flank_empty_message = gr.Markdown(
+                                                value='<div style="text-align: center; padding: 60px 20px; color: #888;">'
+                                                '<p style="font-size: 16px;">No reference images available for this body part</p>'
+                                                "</div>",
+                                                visible=False,
+                                            )
+                                            gallery_left_flank = gr.Gallery(
+                                                columns=6,
+                                                height=400,
+                                                object_fit="scale-down",
+                                                allow_preview=True,
+                                            )
+
+                                        with gr.Tab("Right Flank"):
+                                            right_flank_indicator = gr.Markdown("")
+                                            right_flank_empty_message = gr.Markdown(
+                                                value='<div style="text-align: center; padding: 60px 20px; color: #888;">'
+                                                '<p style="font-size: 16px;">No reference images available for this body part</p>'
+                                                "</div>",
+                                                visible=False,
+                                            )
+                                            gallery_right_flank = gr.Gallery(
+                                                columns=6,
+                                                height=400,
+                                                object_fit="scale-down",
+                                                allow_preview=True,
+                                            )
+
+                                        with gr.Tab("Tail"):
+                                            tail_indicator = gr.Markdown("")
+                                            tail_empty_message = gr.Markdown(
+                                                value='<div style="text-align: center; padding: 60px 20px; color: #888;">'
+                                                '<p style="font-size: 16px;">No reference images available for this body part</p>'
+                                                "</div>",
+                                                visible=False,
+                                            )
+                                            gallery_tail = gr.Gallery(
+                                                columns=6,
+                                                height=400,
+                                                object_fit="scale-down",
+                                                allow_preview=True,
+                                            )
+
+                                        with gr.Tab("Other"):
+                                            misc_indicator = gr.Markdown("")
+                                            misc_empty_message = gr.Markdown(
+                                                value='<div style="text-align: center; padding: 60px 20px; color: #888;">'
+                                                '<p style="font-size: 16px;">No reference images available for this body part</p>'
+                                                "</div>",
+                                                visible=False,
+                                            )
+                                            gallery_misc = gr.Gallery(
+                                                columns=6,
+                                                height=400,
+                                                object_fit="scale-down",
+                                                allow_preview=True,
+                                            )
+
+                # Connect submit button
+                submit_btn.click(
+                    fn=lambda img, ext, top_k, locs, parts, ex_path: run_identification(
+                        image=img,
+                        extractor=ext,
+                        top_k=int(top_k),
+                        selected_locations=locs,
+                        selected_body_parts=parts,
+                        example_path=ex_path,
+                        config=config,
+                    ),
+                    inputs=[
+                        image_input,
+                        extractor_dropdown,
+                        top_k_input,
+                        location_filter,
+                        body_part_filter,
+                        selected_example_state,
+                    ],
+                    outputs=[
+                        # Pipeline outputs (5 total)
+                        result_text,
+                        seg_viz,
+                        cropped_image,
+                        extracted_kpts_viz,
+                        matches_dataset,
+                        # Rank 1 auto-display outputs (18 total)
+                        matched_kpts_viz,
+                        clean_comparison_viz,
+                        selected_match_header,
+                        head_indicator,
+                        left_flank_indicator,
+                        right_flank_indicator,
+                        tail_indicator,
+                        misc_indicator,
+                        head_empty_message,
+                        left_flank_empty_message,
+                        right_flank_empty_message,
+                        tail_empty_message,
+                        misc_empty_message,
+                        gallery_head,
+                        gallery_left_flank,
+                        gallery_right_flank,
+                        gallery_tail,
+                        gallery_misc,
+                    ],
+                )
+
+                # Connect dataset selection
+                matches_dataset.select(
+                    fn=on_match_selected,
+                    outputs=[
+                        matched_kpts_viz,
+                        clean_comparison_viz,
+                        selected_match_header,
+                        head_indicator,
+                        left_flank_indicator,
+                        right_flank_indicator,
+                        tail_indicator,
+                        misc_indicator,
+                        head_empty_message,
+                        left_flank_empty_message,
+                        right_flank_empty_message,
+                        tail_empty_message,
+                        misc_empty_message,
+                        gallery_head,
+                        gallery_left_flank,
+                        gallery_right_flank,
+                        gallery_tail,
+                        gallery_misc,
+                    ],
+                )
+
+            # Tab 2: Explore Catalog
+            with gr.Tab("Explore Catalog"):
+                gr.Markdown(
+                    """
+                    ## Snow Leopard Catalog Browser
+
+                    Browse the reference catalog of known snow leopard individuals.
+                    Each individual has multiple reference images from different body parts and locations.
+                    """
+                )
+
+                # Display catalog statistics
+                stats = catalog_index.get("statistics", {})
+                formatted_locations = [loc.replace("_", " ").title() for loc in stats.get("locations", [])]
+                gr.Markdown(
+                    f"""
+                    ### Catalog Statistics
+                    - **Total Individuals:** {stats.get("total_individuals", "N/A")}
+                    - **Total Images:** {stats.get("total_reference_images", "N/A")}
+                    - **Locations:** {", ".join(formatted_locations)}
+                    - **Body Parts:** {", ".join(stats.get("body_parts", []))}
+                    """
+                )
+
+                gr.Markdown("---")
+                gr.Markdown("### Individual Leopards by Location")
+
+                # Group individuals by location
+                individuals_by_location = {}
+                for individual_data in individuals_data:
+                    location = individual_data.get("location", "unknown")
+                    if location not in individuals_by_location:
+                        individuals_by_location[location] = []
+                    individuals_by_location[location].append(individual_data)
+
+                # Create tabs for each location
+                with gr.Tabs():
+                    for location in sorted(individuals_by_location.keys()):
+                        with gr.Tab(f"{location.replace('_', ' ').title()}"):
+                            # Create subtabs for each individual in this location
+                            with gr.Tabs():
+                                for leopard_data in individuals_by_location[location]:
+                                    create_leopard_tab(
+                                        leopard_metadata=leopard_data, config=config
+                                    )
+
+        # Cleanup on app close
+        app.unload(cleanup_temp_files)
+
+        # Load first example image on startup
+        def load_first_example():
+            """Load the first example image when the app starts."""
+            if example_images:
+                try:
+                    first_image = Image.open(example_images[0])
+                    return first_image
+                except Exception as e:
+                    logger.error(f"Error loading first example image: {e}")
+                    return None
+            return None
+
+        app.load(fn=load_first_example, outputs=[image_input])
+
+    return app
+
+
+if __name__ == "__main__":
+    # Ensure SAM model is downloaded
+    logger.info("Checking for SAM HQ model...")
+    sam_path = ensure_sam_model()
+
+    # Validate required directories exist
+    if not CATALOG_ROOT.exists():
+        logger.error(f"Catalog not found: {CATALOG_ROOT}")
+        logger.error("Please ensure catalog data is present in data/catalog/")
+        exit(1)
+
+    if not EXAMPLES_DIR.exists():
+        logger.warning(f"Examples directory not found: {EXAMPLES_DIR}")
+        EXAMPLES_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Create config
+    config = AppConfig(
+        model_path=None,  # Not using YOLO
+        catalog_root=CATALOG_ROOT,
+        examples_dir=EXAMPLES_DIR,
+        top_k=TOP_K_DEFAULT,
+        port=7860,
+        share=False,
+        sam_checkpoint_path=sam_path,
+        sam_model_type=SAM_MODEL_TYPE,
+        gdino_model_id=GDINO_MODEL_ID,
+        text_prompt=TEXT_PROMPT,
+    )
+
+    # Build and launch app
+    logger.info("Building Gradio interface...")
+    app = create_app(config)
+
+    logger.info("Launching app...")
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+    )

data/cache.tar.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8d9e2f29be8e2e38d250becadb88625bb598a9a7359e1107a90b48edbfadddcc
+size 213437895

data/catalog.tar.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:034ffb5eec607ebcce6372a725d947f0607866d9d89272e2d20b32604ffcfbe7
+size 276174890

pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "snowleopard-reid-gradio"
+version = "0.1.0"
+description = "Snow Leopard Re-Identification Gradio App for Hugging Face Spaces"
+requires-python = ">=3.11"
+dependencies = [
+    "gradio>=5.49.1",
+    "torch>=2.0.0",
+    "transformers>=4.30.0",
+    "timm>=0.9.0",
+    "ultralytics>=8.3.78",
+    "segment-anything-hq>=0.3.0",
+    "lightglue @ git+https://github.com/cvg/LightGlue.git",
+    "opencv-python>=4.11.0.86",
+    "numpy>=2.0.0",
+    "pillow>=11.0.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.0",
+    "matplotlib>=3.8.0",
+    "scipy>=1.10.0",
+    "huggingface_hub>=0.20.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/snowleopard_reid"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

requirements.txt

@@ -0,0 +1,24 @@
+# Core ML
+torch>=2.0.0
+transformers>=4.30.0
+timm>=0.9.0
+ultralytics>=8.3.78
+segment-anything-hq>=0.3.0
+
+# Feature matching (git install)
+lightglue @ git+https://github.com/cvg/LightGlue.git
+
+# Web UI
+gradio>=5.49.1
+
+# Image processing
+opencv-python>=4.11.0.86
+numpy>=2.0.0
+pillow>=11.0.0
+matplotlib>=3.8.0
+
+# Utilities
+pydantic>=2.0.0
+pyyaml>=6.0.0
+scipy>=1.10.0
+huggingface_hub>=0.20.0

scripts/create_archives.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Create compressed archives of catalog and cache data.
+
+This script packages the catalog and cached_results directories into
+tar.gz archives for efficient storage in Git LFS.
+
+Usage:
+    # Create both archives
+    python scripts/create_archives.py
+
+    # Create only catalog archive
+    python scripts/create_archives.py --catalog-only
+
+    # Create only cache archive
+    python scripts/create_archives.py --cache-only
+
+    # Show archive info without creating
+    python scripts/create_archives.py --info
+"""
+
+import argparse
+import logging
+import tarfile
+from pathlib import Path
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+# Paths
+PROJECT_ROOT = Path(__file__).parent.parent
+CATALOG_DIR = PROJECT_ROOT / "data" / "catalog"
+CACHE_DIR = PROJECT_ROOT / "cached_results"
+CATALOG_ARCHIVE = PROJECT_ROOT / "data" / "catalog.tar.gz"
+CACHE_ARCHIVE = PROJECT_ROOT / "data" / "cache.tar.gz"
+
+
+def get_dir_size(path: Path) -> int:
+    """Get total size of directory in bytes."""
+    return sum(f.stat().st_size for f in path.rglob("*") if f.is_file())
+
+
+def get_file_count(path: Path) -> int:
+    """Get total number of files in directory."""
+    return sum(1 for f in path.rglob("*") if f.is_file())
+
+
+def format_size(size_bytes: int) -> str:
+    """Format size in human-readable format."""
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size_bytes < 1024:
+            return f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024
+    return f"{size_bytes:.1f} TB"
+
+
+def create_archive(source_dir: Path, archive_path: Path) -> None:
+    """Create a tar.gz archive from a directory.
+
+    Args:
+        source_dir: Directory to archive
+        archive_path: Output archive path
+    """
+    if not source_dir.exists():
+        logger.error(f"Source directory not found: {source_dir}")
+        return
+
+    source_size = get_dir_size(source_dir)
+    file_count = get_file_count(source_dir)
+    logger.info(f"Archiving {source_dir.name}/")
+    logger.info(f"  Source: {format_size(source_size)} ({file_count} files)")
+
+    # Create archive
+    archive_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with tarfile.open(archive_path, "w:gz") as tar:
+        # Add directory with its name as the archive root
+        tar.add(source_dir, arcname=source_dir.name)
+
+    archive_size = archive_path.stat().st_size
+    compression_ratio = (1 - archive_size / source_size) * 100 if source_size > 0 else 0
+
+    logger.info(f"  Archive: {format_size(archive_size)}")
+    logger.info(f"  Compression: {compression_ratio:.1f}% reduction")
+    logger.info(f"  Created: {archive_path}")
+
+
+def show_info() -> None:
+    """Show information about directories and existing archives."""
+    print("\n=== Directory Info ===")
+
+    for name, path in [("Catalog", CATALOG_DIR), ("Cache", CACHE_DIR)]:
+        if path.exists():
+            size = get_dir_size(path)
+            count = get_file_count(path)
+            print(f"{name}: {format_size(size)} ({count} files)")
+        else:
+            print(f"{name}: not found")
+
+    print("\n=== Archive Info ===")
+
+    for name, path in [("Catalog", CATALOG_ARCHIVE), ("Cache", CACHE_ARCHIVE)]:
+        if path.exists():
+            size = path.stat().st_size
+            print(f"{name}: {format_size(size)}")
+        else:
+            print(f"{name}: not created")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create compressed archives of catalog and cache data"
+    )
+    parser.add_argument(
+        "--catalog-only",
+        action="store_true",
+        help="Only create catalog archive",
+    )
+    parser.add_argument(
+        "--cache-only",
+        action="store_true",
+        help="Only create cache archive",
+    )
+    parser.add_argument(
+        "--info",
+        action="store_true",
+        help="Show info about directories and archives",
+    )
+
+    args = parser.parse_args()
+
+    if args.info:
+        show_info()
+        return
+
+    # Determine what to archive
+    do_catalog = not args.cache_only
+    do_cache = not args.catalog_only
+
+    if do_catalog:
+        create_archive(CATALOG_DIR, CATALOG_ARCHIVE)
+
+    if do_cache:
+        create_archive(CACHE_DIR, CACHE_ARCHIVE)
+
+    print("\n=== Summary ===")
+    show_info()
+
+
+if __name__ == "__main__":
+    main()

scripts/precompute_cache.py

@@ -0,0 +1,515 @@
+#!/usr/bin/env python3
+"""Pre-compute pipeline results for all example images.
+
+This script runs the full snow leopard identification pipeline on all example images
+with all available feature extractors, caching the results for instant display
+in the Gradio app.
+
+Usage:
+    # Process all example images with all extractors
+    python scripts/precompute_cache.py
+
+    # Process specific images
+    python scripts/precompute_cache.py --images IMG_001.jpg IMG_002.jpg
+
+    # Process with specific extractors only
+    python scripts/precompute_cache.py --extractors sift superpoint
+
+    # Clear cache and regenerate all
+    python scripts/precompute_cache.py --clear
+
+    # Show cache summary
+    python scripts/precompute_cache.py --summary
+"""
+
+import argparse
+import logging
+import sys
+import tempfile
+from pathlib import Path
+
+import cv2
+import numpy as np
+import torch
+from PIL import Image
+
+# Add project root to path for imports
+PROJECT_ROOT = Path(__file__).parent.parent
+sys.path.insert(0, str(PROJECT_ROOT / "src"))
+
+from snowleopard_reid.cache import (
+    CACHE_DIR,
+    clear_cache,
+    extract_location_body_part_from_filepath,
+    get_cache_dir,
+    get_cache_summary,
+)
+from snowleopard_reid.pipeline.stages import (
+    run_feature_extraction_stage,
+    run_matching_stage,
+    run_preprocess_stage,
+    run_segmentation_stage,
+    select_best_mask,
+)
+from snowleopard_reid.pipeline.stages.segmentation import (
+    load_gdino_model,
+    load_sam_predictor,
+)
+from snowleopard_reid.visualization import draw_keypoints_overlay
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+# Configuration
+CATALOG_ROOT = PROJECT_ROOT / "data" / "catalog"
+SAM_CHECKPOINT_DIR = PROJECT_ROOT / "data" / "models"
+SAM_CHECKPOINT_NAME = "sam_hq_vit_l.pth"
+EXAMPLES_DIR = PROJECT_ROOT / "data" / "examples"
+GDINO_MODEL_ID = "IDEA-Research/grounding-dino-base"
+TEXT_PROMPT = "a snow leopard."
+SAM_MODEL_TYPE = "vit_l"
+# Set very high to get ALL matches (will be limited by catalog size)
+TOP_K_ALL = 1000
+# Default top_k for display
+TOP_K_DEFAULT = 5
+
+# All available extractors
+ALL_EXTRACTORS = ["sift", "superpoint", "disk", "aliked"]
+
+
+def ensure_sam_model() -> Path:
+    """Download SAM HQ model if not present.
+
+    Returns:
+        Path to the SAM HQ checkpoint file
+    """
+    from huggingface_hub import hf_hub_download
+
+    sam_path = SAM_CHECKPOINT_DIR / SAM_CHECKPOINT_NAME
+    if not sam_path.exists():
+        logger.info("Downloading SAM HQ model (1.6GB)...")
+        SAM_CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+        hf_hub_download(
+            repo_id="lkeab/hq-sam",
+            filename=SAM_CHECKPOINT_NAME,
+            local_dir=SAM_CHECKPOINT_DIR,
+        )
+        logger.info("SAM HQ model downloaded successfully")
+    return sam_path
+
+
+def create_segmentation_viz(image_path: Path, mask: np.ndarray) -> Image.Image:
+    """Create visualization of segmentation mask overlaid on image.
+
+    Args:
+        image_path: Path to original image
+        mask: Binary segmentation mask
+
+    Returns:
+        PIL Image with segmentation overlay
+    """
+    img = cv2.imread(str(image_path))
+    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+
+    # Resize mask to match image dimensions if needed
+    if mask.shape[:2] != img_rgb.shape[:2]:
+        mask_resized = cv2.resize(
+            mask.astype(np.uint8),
+            (img_rgb.shape[1], img_rgb.shape[0]),
+            interpolation=cv2.INTER_NEAREST,
+        )
+    else:
+        mask_resized = mask
+
+    # Create colored overlay
+    overlay = img_rgb.copy()
+    overlay[mask_resized > 0] = [255, 0, 0]  # Red for masked region
+
+    # Blend
+    alpha = 0.4
+    blended = cv2.addWeighted(img_rgb, 1 - alpha, overlay, alpha, 0)
+
+    return Image.fromarray(blended)
+
+
+def process_and_cache(
+    image_path: Path,
+    extractor: str,
+    gdino_processor,
+    gdino_model,
+    sam_predictor,
+    device: str,
+) -> bool:
+    """Run full pipeline and cache ALL results for one image/extractor combination.
+
+    This version caches ALL matches (not just top-k) with location/body_part
+    metadata, and stores NPZ pairwise data for on-demand visualization generation.
+
+    Args:
+        image_path: Path to example image
+        extractor: Feature extractor to use
+        gdino_processor: Pre-loaded Grounding DINO processor
+        gdino_model: Pre-loaded Grounding DINO model
+        sam_predictor: Pre-loaded SAM HQ predictor
+        device: Device to run on ('cuda' or 'cpu')
+
+    Returns:
+        True if successful, False otherwise
+    """
+    logger.info(f"Processing {image_path.name} with {extractor.upper()}...")
+
+    try:
+        # Create temporary directory for intermediate files
+        with tempfile.TemporaryDirectory(prefix="snowleopard_cache_") as temp_dir:
+            temp_dir = Path(temp_dir)
+
+            # ================================================================
+            # Stage 1: Segmentation (GDINO+SAM)
+            # ================================================================
+            logger.info("  Running GDINO+SAM segmentation...")
+            seg_stage = run_segmentation_stage(
+                image_path=image_path,
+                strategy="gdino_sam",
+                confidence_threshold=0.2,
+                device=device,
+                gdino_processor=gdino_processor,
+                gdino_model=gdino_model,
+                sam_predictor=sam_predictor,
+                text_prompt=TEXT_PROMPT,
+                box_threshold=0.30,
+                text_threshold=0.20,
+            )
+
+            predictions = seg_stage["data"]["predictions"]
+            if not predictions:
+                logger.warning(f"  No snow leopards detected in {image_path.name}")
+                return False
+
+            # ================================================================
+            # Stage 2: Mask Selection
+            # ================================================================
+            logger.info("  Selecting best mask...")
+            selected_idx, selected_pred = select_best_mask(
+                predictions,
+                strategy="confidence_area",
+            )
+
+            # Create segmentation visualization
+            segmentation_image = create_segmentation_viz(
+                image_path=image_path,
+                mask=selected_pred["mask"],
+            )
+
+            # ================================================================
+            # Stage 3: Preprocessing
+            # ================================================================
+            logger.info("  Preprocessing...")
+            prep_stage = run_preprocess_stage(
+                image_path=image_path,
+                mask=selected_pred["mask"],
+                padding=5,
+            )
+
+            cropped_image = prep_stage["data"]["cropped_image"]
+
+            # Save cropped image for visualization functions
+            cropped_path = temp_dir / "cropped.jpg"
+            cropped_image.save(cropped_path)
+
+            # ================================================================
+            # Stage 4: Feature Extraction
+            # ================================================================
+            logger.info(f"  Extracting features ({extractor.upper()})...")
+            feat_stage = run_feature_extraction_stage(
+                image=cropped_image,
+                extractor=extractor,
+                max_keypoints=2048,
+                device=device,
+            )
+
+            query_features = feat_stage["data"]["features"]
+
+            # Create keypoints visualization
+            query_kpts = query_features["keypoints"].cpu().numpy()
+            keypoints_image = draw_keypoints_overlay(
+                image_path=cropped_path,
+                keypoints=query_kpts,
+                max_keypoints=500,
+                color="blue",
+                ps=10,
+            )
+
+            # ================================================================
+            # Stage 5: Matching - Get ALL matches
+            # ================================================================
+            logger.info("  Matching against catalog (ALL matches)...")
+            temp_pairwise_dir = temp_dir / "pairwise"
+            temp_pairwise_dir.mkdir(exist_ok=True)
+
+            match_stage = run_matching_stage(
+                query_features=query_features,
+                catalog_path=CATALOG_ROOT,
+                top_k=TOP_K_ALL,  # Get ALL matches
+                extractor=extractor,
+                device=device,
+                query_image_path=str(cropped_path),
+                pairwise_output_dir=temp_pairwise_dir,
+            )
+
+            matches = match_stage["data"]["matches"]
+
+            if not matches:
+                logger.warning(f"  No matches found for {image_path.name}")
+                return False
+
+            logger.info(f"  Found {len(matches)} matches")
+
+            # ================================================================
+            # Enrich matches with location/body_part
+            # ================================================================
+            logger.info("  Adding location/body_part metadata...")
+            for match in matches:
+                location, body_part = extract_location_body_part_from_filepath(
+                    match["filepath"]
+                )
+                match["location"] = location
+                match["body_part"] = body_part
+
+            # ================================================================
+            # Set up cache directory
+            # ================================================================
+            cache_dir = get_cache_dir(image_path, extractor)
+            cache_dir.mkdir(parents=True, exist_ok=True)
+            pairwise_dir = cache_dir / "pairwise"
+            pairwise_dir.mkdir(exist_ok=True)
+
+            # ================================================================
+            # Copy NPZ files with catalog_id naming (not rank-based)
+            # ================================================================
+            logger.info("  Copying NPZ pairwise data...")
+            npz_count = 0
+            for match in matches:
+                catalog_id = match["catalog_id"]
+                rank = match["rank"]
+
+                # Source NPZ (rank-based naming from matching stage)
+                src_npz = temp_pairwise_dir / f"rank_{rank:02d}_{catalog_id}.npz"
+
+                # Destination NPZ (catalog_id naming for cache)
+                dst_npz = pairwise_dir / f"{catalog_id}.npz"
+
+                if src_npz.exists():
+                    import shutil
+                    shutil.copy2(src_npz, dst_npz)
+                    npz_count += 1
+
+            logger.info(f"  Copied {npz_count} NPZ files")
+
+            # ================================================================
+            # Build Predictions Dict (v2.0 format with all_matches)
+            # ================================================================
+            predictions_dict = {
+                "format_version": "2.0",
+                "query_image": str(image_path),
+                "extractor": extractor,
+                "pipeline": {
+                    "segmentation": {
+                        "strategy": "gdino_sam",
+                        "num_predictions": len(predictions),
+                        "selected_idx": selected_idx,
+                        "confidence": float(selected_pred["confidence"]),
+                    },
+                    "preprocessing": {
+                        "padding": prep_stage["config"]["padding"],
+                    },
+                    "features": {
+                        "num_keypoints": int(feat_stage["metrics"]["num_keypoints"]),
+                        "extractor": extractor,
+                        "max_keypoints": 2048,
+                    },
+                    "matching": {
+                        "num_catalog_images": match_stage["metrics"]["num_catalog_images"],
+                        "num_successful_matches": match_stage["metrics"]["num_successful_matches"],
+                    },
+                },
+                "all_matches": matches,  # ALL matches with location/body_part
+                "top_k": TOP_K_DEFAULT,
+            }
+
+            # ================================================================
+            # Save Cache (predictions.json + visualization images)
+            # ================================================================
+            logger.info("  Saving to cache...")
+
+            # Save predictions JSON
+            import json
+            predictions_file = cache_dir / "predictions.json"
+            with open(predictions_file, "w") as f:
+                json.dump(predictions_dict, f, indent=2)
+
+            # Save visualization images
+            segmentation_image.save(cache_dir / "segmentation.png")
+            cropped_image.save(cache_dir / "cropped.png")
+            keypoints_image.save(cache_dir / "keypoints.png")
+
+            # Log cache size
+            cache_size = sum(
+                f.stat().st_size for f in cache_dir.rglob("*") if f.is_file()
+            )
+            logger.info(
+                f"  Cached: {cache_dir.name} ({cache_size / 1024 / 1024:.2f} MB)"
+            )
+            logger.info(f"  {len(matches)} matches, {npz_count} NPZ files")
+
+            return True
+
+    except Exception as e:
+        logger.error(f"  Failed: {e}", exc_info=True)
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Pre-compute pipeline results for example images"
+    )
+    parser.add_argument(
+        "--images",
+        nargs="+",
+        help="Specific image filenames to process (default: all in examples/)",
+    )
+    parser.add_argument(
+        "--extractors",
+        nargs="+",
+        choices=ALL_EXTRACTORS,
+        default=ALL_EXTRACTORS,
+        help="Feature extractors to use (default: all)",
+    )
+    parser.add_argument(
+        "--clear",
+        action="store_true",
+        help="Clear all cached results before processing",
+    )
+    parser.add_argument(
+        "--summary",
+        action="store_true",
+        help="Show cache summary and exit",
+    )
+    parser.add_argument(
+        "--device",
+        choices=["cpu", "cuda"],
+        default=None,
+        help="Device to run on (default: auto-detect)",
+    )
+
+    args = parser.parse_args()
+
+    # Show summary and exit
+    if args.summary:
+        summary = get_cache_summary()
+        print("\n=== Cache Summary ===")
+        print(f"Total cached: {summary['total_cached']} items")
+        print(f"Total size: {summary['total_size_mb']:.2f} MB")
+        print("\nCached items:")
+        for item in summary["cached_items"]:
+            print(f"  - {item['image_stem']} ({item['extractor']}): {item['size_mb']:.2f} MB")
+        return
+
+    # Clear cache if requested
+    if args.clear:
+        logger.info("Clearing cache...")
+        clear_cache()
+        logger.info("Cache cleared")
+
+    # Determine device
+    if args.device:
+        device = args.device
+    else:
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+
+    logger.info(f"Using device: {device}")
+    if device == "cuda":
+        logger.info(f"GPU: {torch.cuda.get_device_name(0)}")
+
+    # Find example images
+    if args.images:
+        image_paths = [EXAMPLES_DIR / img for img in args.images]
+        # Filter existing files
+        image_paths = [p for p in image_paths if p.exists()]
+        if not image_paths:
+            logger.error("No valid image paths found")
+            sys.exit(1)
+    else:
+        image_paths = (
+            list(EXAMPLES_DIR.glob("*.jpg"))
+            + list(EXAMPLES_DIR.glob("*.JPG"))
+            + list(EXAMPLES_DIR.glob("*.png"))
+        )
+
+    if not image_paths:
+        logger.error(f"No example images found in {EXAMPLES_DIR}")
+        sys.exit(1)
+
+    logger.info(f"Found {len(image_paths)} example images")
+    logger.info(f"Extractors: {', '.join(args.extractors)}")
+
+    # Ensure SAM model is downloaded
+    logger.info("Checking for SAM HQ model...")
+    sam_path = ensure_sam_model()
+
+    # Load GDINO model once
+    logger.info(f"Loading Grounding DINO model: {GDINO_MODEL_ID}...")
+    gdino_processor, gdino_model = load_gdino_model(
+        model_id=GDINO_MODEL_ID,
+        device=device,
+    )
+    logger.info("Grounding DINO model loaded")
+
+    # Load SAM HQ model once
+    logger.info(f"Loading SAM HQ model from {sam_path}...")
+    sam_predictor = load_sam_predictor(
+        checkpoint_path=sam_path,
+        model_type=SAM_MODEL_TYPE,
+        device=device,
+    )
+    logger.info("SAM HQ model loaded")
+
+    # Process all combinations
+    total = len(image_paths) * len(args.extractors)
+    success = 0
+    failed = 0
+
+    for i, image_path in enumerate(image_paths):
+        for j, extractor in enumerate(args.extractors):
+            current = i * len(args.extractors) + j + 1
+            logger.info(f"\n[{current}/{total}] Processing...")
+
+            if process_and_cache(
+                image_path=image_path,
+                extractor=extractor,
+                gdino_processor=gdino_processor,
+                gdino_model=gdino_model,
+                sam_predictor=sam_predictor,
+                device=device,
+            ):
+                success += 1
+            else:
+                failed += 1
+
+    # Final summary
+    logger.info("\n" + "=" * 50)
+    logger.info("PRECOMPUTATION COMPLETE")
+    logger.info("=" * 50)
+    logger.info(f"Success: {success}/{total}")
+    logger.info(f"Failed: {failed}/{total}")
+
+    # Show cache summary
+    summary = get_cache_summary()
+    logger.info(f"Total cache size: {summary['total_size_mb']:.2f} MB")
+
+
+if __name__ == "__main__":
+    main()

src/snowleopard_reid/__init__.py

@@ -0,0 +1,27 @@
+"""Snow Leopard Re-Identification Package."""
+
+from snowleopard_reid.cache import (
+    clear_cache,
+    get_cache_summary,
+    is_cached,
+    load_cached_match_visualizations,
+    load_cached_results,
+    save_cache_results,
+)
+from snowleopard_reid.images import resize_image_if_needed
+from snowleopard_reid.utils import get_device
+
+__all__ = [
+    "clear_cache",
+    "get_cache_summary",
+    "get_device",
+    "is_cached",
+    "load_cached_match_visualizations",
+    "load_cached_results",
+    "resize_image_if_needed",
+    "save_cache_results",
+]
+
+
+def main() -> None:
+    print("Hello from snowleopard-reid!")

src/snowleopard_reid/cache.py

@@ -0,0 +1,421 @@
+"""Cache utilities for precomputed pipeline results.
+
+This module provides functions for loading and saving cached pipeline results,
+enabling instant display of results for example images without running the
+expensive pipeline (GDINO+SAM segmentation, feature extraction, matching) on CPU.
+
+Cache Structure (v2.0 - supports filtering):
+    cached_results/
+    ├── {image_stem}_{extractor}/
+    │   ├── predictions.json          # ALL matches with location/body_part
+    │   ├── segmentation.png          # Segmentation visualization
+    │   ├── cropped.png               # Cropped snow leopard image
+    │   ├── keypoints.png             # Extracted keypoints visualization
+    │   └── pairwise/
+    │       ├── {catalog_id}.npz      # NPZ data for ALL matches
+    │       └── ...                   # (visualizations generated on-demand)
+"""
+
+import copy
+import json
+import logging
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from snowleopard_reid.visualization import (
+    draw_matched_keypoints,
+    draw_side_by_side_comparison,
+)
+
+logger = logging.getLogger(__name__)
+
+# Cache directory relative to project root
+CACHE_DIR = Path("cached_results")
+
+
+def get_cache_key(image_path: Path | str, extractor: str) -> str:
+    """Generate cache key from image stem and extractor.
+
+    Args:
+        image_path: Path to the query image
+        extractor: Feature extractor name (e.g., 'sift', 'superpoint')
+
+    Returns:
+        Cache key string in format "{image_stem}_{extractor}"
+    """
+    image_path = Path(image_path)
+    return f"{image_path.stem}_{extractor}"
+
+
+def get_cache_dir(image_path: Path | str, extractor: str) -> Path:
+    """Get cache directory for an image/extractor combination.
+
+    Args:
+        image_path: Path to the query image
+        extractor: Feature extractor name
+
+    Returns:
+        Path to the cache directory
+    """
+    return CACHE_DIR / get_cache_key(image_path, extractor)
+
+
+def is_cached(image_path: Path | str, extractor: str) -> bool:
+    """Check if results are cached for this image/extractor combination.
+
+    Args:
+        image_path: Path to the query image
+        extractor: Feature extractor name
+
+    Returns:
+        True if all required cache files exist
+    """
+    cache_dir = get_cache_dir(image_path, extractor)
+    predictions_file = cache_dir / "predictions.json"
+
+    if not predictions_file.exists():
+        return False
+
+    # Check for required visualization files
+    required_files = [
+        "segmentation.png",
+        "cropped.png",
+        "keypoints.png",
+    ]
+
+    for filename in required_files:
+        if not (cache_dir / filename).exists():
+            return False
+
+    return True
+
+
+def load_cached_results(image_path: Path | str, extractor: str) -> dict:
+    """Load all cached results for an image/extractor combination.
+
+    Args:
+        image_path: Path to the query image
+        extractor: Feature extractor name
+
+    Returns:
+        Dictionary containing:
+            - predictions: Full pipeline predictions dict
+            - segmentation_image: PIL Image of segmentation overlay
+            - cropped_image: PIL Image of cropped snow leopard
+            - keypoints_image: PIL Image of extracted keypoints
+            - pairwise_dir: Path to directory with match visualizations
+
+    Raises:
+        FileNotFoundError: If cache files don't exist
+    """
+    cache_dir = get_cache_dir(image_path, extractor)
+
+    if not cache_dir.exists():
+        raise FileNotFoundError(f"Cache directory not found: {cache_dir}")
+
+    predictions_file = cache_dir / "predictions.json"
+    if not predictions_file.exists():
+        raise FileNotFoundError(f"Predictions file not found: {predictions_file}")
+
+    # Load predictions JSON
+    with open(predictions_file) as f:
+        predictions = json.load(f)
+
+    # Load visualization images
+    segmentation_image = Image.open(cache_dir / "segmentation.png")
+    cropped_image = Image.open(cache_dir / "cropped.png")
+    keypoints_image = Image.open(cache_dir / "keypoints.png")
+
+    return {
+        "predictions": predictions,
+        "segmentation_image": segmentation_image,
+        "cropped_image": cropped_image,
+        "keypoints_image": keypoints_image,
+        "pairwise_dir": cache_dir / "pairwise",
+    }
+
+
+def load_cached_match_visualizations(
+    pairwise_dir: Path,
+    matches: list[dict],
+) -> tuple[dict, dict]:
+    """Load cached match and clean comparison visualizations.
+
+    Args:
+        pairwise_dir: Path to pairwise visualizations directory
+        matches: List of match dictionaries with rank and catalog_id
+
+    Returns:
+        Tuple of (match_visualizations, clean_comparison_visualizations)
+        Both are dicts mapping rank -> PIL Image
+    """
+    match_visualizations = {}
+    clean_comparison_visualizations = {}
+
+    for match in matches:
+        rank = match["rank"]
+        catalog_id = match["catalog_id"]
+
+        # Load match visualization
+        match_path = pairwise_dir / f"rank_{rank:02d}_{catalog_id}_match.png"
+        if match_path.exists():
+            match_visualizations[rank] = Image.open(match_path)
+
+        # Load clean comparison visualization
+        clean_path = pairwise_dir / f"rank_{rank:02d}_{catalog_id}_clean.png"
+        if clean_path.exists():
+            clean_comparison_visualizations[rank] = Image.open(clean_path)
+
+    return match_visualizations, clean_comparison_visualizations
+
+
+def save_cache_results(
+    image_path: Path | str,
+    extractor: str,
+    predictions: dict,
+    segmentation_image: Image.Image,
+    cropped_image: Image.Image,
+    keypoints_image: Image.Image,
+    match_visualizations: dict[int, Image.Image],
+    clean_comparison_visualizations: dict[int, Image.Image],
+    matches: list[dict],
+) -> Path:
+    """Save pipeline results to cache.
+
+    Args:
+        image_path: Path to the original query image
+        extractor: Feature extractor name
+        predictions: Full pipeline predictions dictionary
+        segmentation_image: PIL Image of segmentation overlay
+        cropped_image: PIL Image of cropped snow leopard
+        keypoints_image: PIL Image of extracted keypoints
+        match_visualizations: Dict mapping rank -> match visualization PIL Image
+        clean_comparison_visualizations: Dict mapping rank -> clean comparison PIL Image
+        matches: List of match dictionaries with rank and catalog_id
+
+    Returns:
+        Path to the cache directory
+    """
+    cache_dir = get_cache_dir(image_path, extractor)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    # Save predictions JSON
+    predictions_file = cache_dir / "predictions.json"
+    with open(predictions_file, "w") as f:
+        json.dump(predictions, f, indent=2)
+    logger.info(f"Saved predictions: {predictions_file}")
+
+    # Save visualization images
+    segmentation_image.save(cache_dir / "segmentation.png")
+    cropped_image.save(cache_dir / "cropped.png")
+    keypoints_image.save(cache_dir / "keypoints.png")
+    logger.info(f"Saved visualization images to {cache_dir}")
+
+    # Save pairwise match visualizations
+    pairwise_dir = cache_dir / "pairwise"
+    pairwise_dir.mkdir(exist_ok=True)
+
+    for match in matches:
+        rank = match["rank"]
+        catalog_id = match["catalog_id"]
+
+        # Save match visualization
+        if rank in match_visualizations:
+            match_path = pairwise_dir / f"rank_{rank:02d}_{catalog_id}_match.png"
+            match_visualizations[rank].save(match_path)
+
+        # Save clean comparison visualization
+        if rank in clean_comparison_visualizations:
+            clean_path = pairwise_dir / f"rank_{rank:02d}_{catalog_id}_clean.png"
+            clean_comparison_visualizations[rank].save(clean_path)
+
+    logger.info(f"Saved {len(match_visualizations)} pairwise visualizations")
+
+    return cache_dir
+
+
+def clear_cache(image_path: Path | str = None, extractor: str = None) -> None:
+    """Clear cache directory.
+
+    Args:
+        image_path: If provided, only clear cache for this image
+        extractor: If provided with image_path, only clear specific cache
+    """
+    import shutil
+
+    if image_path and extractor:
+        # Clear specific cache
+        cache_dir = get_cache_dir(image_path, extractor)
+        if cache_dir.exists():
+            shutil.rmtree(cache_dir)
+            logger.info(f"Cleared cache: {cache_dir}")
+    elif CACHE_DIR.exists():
+        # Clear all caches
+        shutil.rmtree(CACHE_DIR)
+        logger.info(f"Cleared all caches: {CACHE_DIR}")
+
+
+def get_cache_summary() -> dict:
+    """Get summary of cached results.
+
+    Returns:
+        Dictionary with cache statistics
+    """
+    if not CACHE_DIR.exists():
+        return {"total_cached": 0, "total_size_mb": 0, "cached_items": []}
+
+    cached_items = []
+    total_size = 0
+
+    for cache_dir in CACHE_DIR.iterdir():
+        if cache_dir.is_dir():
+            # Calculate size
+            size = sum(f.stat().st_size for f in cache_dir.rglob("*") if f.is_file())
+            total_size += size
+
+            # Parse cache key
+            parts = cache_dir.name.rsplit("_", 1)
+            if len(parts) == 2:
+                image_stem, extractor = parts
+            else:
+                image_stem, extractor = cache_dir.name, "unknown"
+
+            cached_items.append({
+                "image_stem": image_stem,
+                "extractor": extractor,
+                "size_mb": size / (1024 * 1024),
+                "path": str(cache_dir),
+            })
+
+    return {
+        "total_cached": len(cached_items),
+        "total_size_mb": total_size / (1024 * 1024),
+        "cached_items": cached_items,
+    }
+
+
+def filter_cached_matches(
+    all_matches: list[dict],
+    filter_locations: list[str] | None = None,
+    filter_body_parts: list[str] | None = None,
+    top_k: int = 5,
+) -> list[dict]:
+    """Filter cached matches by location/body_part and return top-k.
+
+    Args:
+        all_matches: List of all cached match dictionaries
+        filter_locations: List of locations to filter by (e.g., ["skycrest_valley"])
+        filter_body_parts: List of body parts to filter by (e.g., ["head", "right_flank"])
+        top_k: Number of top matches to return after filtering
+
+    Returns:
+        List of filtered and re-ranked match dictionaries
+    """
+    # Make a deep copy to avoid modifying the original
+    filtered = [copy.deepcopy(m) for m in all_matches]
+
+    if filter_locations:
+        filtered = [m for m in filtered if m.get("location") in filter_locations]
+
+    if filter_body_parts:
+        filtered = [m for m in filtered if m.get("body_part") in filter_body_parts]
+
+    # Re-sort by wasserstein (descending - higher is better)
+    filtered = sorted(filtered, key=lambda x: x.get("wasserstein", 0), reverse=True)
+
+    # Re-assign ranks for the filtered top-k
+    for i, match in enumerate(filtered[:top_k]):
+        match["rank"] = i + 1
+
+    return filtered[:top_k]
+
+
+def generate_visualizations_from_npz(
+    pairwise_dir: Path,
+    matches: list[dict],
+    cropped_image_path: Path | str,
+) -> tuple[dict, dict]:
+    """Generate match visualizations on-demand from cached NPZ data.
+
+    Args:
+        pairwise_dir: Path to directory containing NPZ pairwise data files
+        matches: List of filtered match dictionaries with catalog_id and filepath
+        cropped_image_path: Path to the cropped query image
+
+    Returns:
+        Tuple of (match_visualizations, clean_comparison_visualizations)
+        Both are dicts mapping rank -> PIL Image
+    """
+    match_visualizations = {}
+    clean_comparison_visualizations = {}
+
+    cropped_image_path = Path(cropped_image_path)
+
+    for match in matches:
+        rank = match["rank"]
+        catalog_id = match["catalog_id"]
+        catalog_image_path = Path(match["filepath"])
+
+        # Look for NPZ file by catalog_id
+        npz_path = pairwise_dir / f"{catalog_id}.npz"
+
+        if npz_path.exists():
+            try:
+                pairwise_data = np.load(npz_path, allow_pickle=True)
+
+                # Generate matched keypoints visualization
+                match_viz = draw_matched_keypoints(
+                    query_image_path=cropped_image_path,
+                    catalog_image_path=catalog_image_path,
+                    query_keypoints=pairwise_data["query_keypoints"],
+                    catalog_keypoints=pairwise_data["catalog_keypoints"],
+                    match_scores=pairwise_data["match_scores"],
+                    max_matches=100,
+                )
+                match_visualizations[rank] = match_viz
+
+                # Generate clean side-by-side comparison
+                clean_viz = draw_side_by_side_comparison(
+                    query_image_path=cropped_image_path,
+                    catalog_image_path=catalog_image_path,
+                )
+                clean_comparison_visualizations[rank] = clean_viz
+
+            except Exception as e:
+                logger.warning(
+                    f"Failed to generate visualization for {catalog_id}: {e}"
+                )
+        else:
+            logger.warning(f"NPZ file not found for {catalog_id}: {npz_path}")
+
+    return match_visualizations, clean_comparison_visualizations
+
+
+def extract_location_body_part_from_filepath(filepath: str) -> tuple[str, str]:
+    """Extract location and body_part from catalog image filepath.
+
+    Expected filepath format:
+        .../database/{location}/{individual}/images/{body_part}/{filename}
+
+    Args:
+        filepath: Path to catalog image
+
+    Returns:
+        Tuple of (location, body_part)
+    """
+    parts = Path(filepath).parts
+
+    # Find "database" in path and extract location (next part) and body_part
+    try:
+        db_idx = parts.index("database")
+        location = parts[db_idx + 1] if db_idx + 1 < len(parts) else "unknown"
+
+        # Find "images" in path and get body_part (next part)
+        img_idx = parts.index("images")
+        body_part = parts[img_idx + 1] if img_idx + 1 < len(parts) else "unknown"
+
+        return location, body_part
+    except (ValueError, IndexError):
+        return "unknown", "unknown"

src/snowleopard_reid/catalog/__init__.py

@@ -0,0 +1,25 @@
+"""Catalog module for snow leopard re-identification.
+
+This module provides utilities for loading and managing the snow leopard catalog,
+including individual metadata and feature data.
+"""
+
+from .loader import (
+    get_all_catalog_features,
+    get_available_body_parts,
+    get_available_locations,
+    get_catalog_metadata_for_id,
+    get_filtered_catalog_features,
+    load_catalog_index,
+    load_leopard_metadata,
+)
+
+__all__ = [
+    "load_catalog_index",
+    "load_leopard_metadata",
+    "get_all_catalog_features",
+    "get_filtered_catalog_features",
+    "get_available_locations",
+    "get_available_body_parts",
+    "get_catalog_metadata_for_id",
+]

src/snowleopard_reid/catalog/loader.py

@@ -0,0 +1,379 @@
+"""Utilities for loading and managing the snow leopard catalog.
+
+This module provides functions for loading catalog metadata, individual leopard
+information, and catalog features for matching operations.
+"""
+
+from pathlib import Path
+
+import torch
+import yaml
+
+
+def load_catalog_index(catalog_root: Path) -> dict:
+    """Load the catalog index YAML file.
+
+    Args:
+        catalog_root: Path to catalog root directory (e.g., data/08_catalog/v1.0/)
+
+    Returns:
+        Dictionary with catalog index data including:
+            - catalog_version: str
+            - feature_extractors: dict
+            - individuals: list
+            - statistics: dict
+
+    Raises:
+        FileNotFoundError: If catalog index file doesn't exist
+        yaml.YAMLError: If YAML parsing fails
+    """
+    index_path = catalog_root / "catalog_index.yaml"
+
+    if not index_path.exists():
+        raise FileNotFoundError(f"Catalog index not found: {index_path}")
+
+    try:
+        with open(index_path) as f:
+            index = yaml.safe_load(f)
+        return index
+    except yaml.YAMLError as e:
+        raise yaml.YAMLError(f"Failed to parse catalog index: {e}")
+
+
+def load_leopard_metadata(metadata_path: Path) -> dict:
+    """Load metadata YAML file for a specific leopard.
+
+    Args:
+        metadata_path: Path to leopard metadata.yaml file
+
+    Returns:
+        Dictionary with leopard metadata including:
+            - individual_id: str
+            - leopard_name: str
+            - reference_images: list
+            - statistics: dict
+
+    Raises:
+        FileNotFoundError: If metadata file doesn't exist
+        yaml.YAMLError: If YAML parsing fails
+    """
+    if not metadata_path.exists():
+        raise FileNotFoundError(f"Leopard metadata not found: {metadata_path}")
+
+    try:
+        with open(metadata_path) as f:
+            metadata = yaml.safe_load(f)
+        return metadata
+    except yaml.YAMLError as e:
+        raise yaml.YAMLError(f"Failed to parse leopard metadata: {e}")
+
+
+def get_all_catalog_features(
+    catalog_root: Path,
+    extractor: str = "sift",
+) -> dict[str, dict[str, torch.Tensor]]:
+    """Load all catalog features for a specific extractor.
+
+    Args:
+        catalog_root: Path to catalog root directory (e.g., data/08_catalog/v1.0/)
+        extractor: Feature extractor name (default: 'sift')
+
+    Returns:
+        Dictionary mapping catalog_id to feature dict:
+            {
+                "leopard1_2022_001": {
+                    "keypoints": torch.Tensor,
+                    "descriptors": torch.Tensor,
+                    "scores": torch.Tensor,
+                    ...
+                },
+                ...
+            }
+
+    Raises:
+        FileNotFoundError: If catalog doesn't exist
+        ValueError: If no features found for extractor
+    """
+    if not catalog_root.exists():
+        raise FileNotFoundError(f"Catalog root not found: {catalog_root}")
+
+    # Load catalog index to get all individuals
+    index = load_catalog_index(catalog_root)
+
+    # Check if extractor is available
+    available_extractors = index.get("feature_extractors", {})
+    if extractor not in available_extractors:
+        raise ValueError(
+            f"Extractor '{extractor}' not available in catalog. "
+            f"Available: {list(available_extractors.keys())}"
+        )
+
+    catalog_features = {}
+    database_dir = catalog_root / "database"
+
+    # Load features for each individual
+    for individual in index["individuals"]:
+        # Support both 'leopard_name' and 'individual_name' keys
+        leopard_name = individual.get("leopard_name") or individual.get(
+            "individual_name"
+        )
+        location = individual.get("location", "")
+
+        # Construct path: database/{location}/{individual_name}/
+        if location:
+            leopard_dir = database_dir / location / leopard_name
+        else:
+            leopard_dir = database_dir / leopard_name
+
+        # Load leopard metadata to get all reference images
+        metadata_path = leopard_dir / "metadata.yaml"
+        metadata = load_leopard_metadata(metadata_path)
+
+        # Load features for each reference image
+        for ref_image in metadata["reference_images"]:
+            # Check if features exist for this extractor
+            if extractor not in ref_image.get("features", {}):
+                continue
+
+            # Get feature path (relative to database directory in metadata)
+            feature_rel_path = ref_image["features"][extractor]
+            feature_path = database_dir / feature_rel_path
+
+            if not feature_path.exists():
+                # Skip missing features with a warning
+                continue
+
+            # Create catalog ID: leopard_name_year_imagenum
+            # e.g., "naguima_2022_001"
+            image_id = ref_image["image_id"]
+            catalog_id = f"{leopard_name.lower().replace(' ', '_')}_{image_id}"
+
+            # Load features
+            try:
+                feats = torch.load(feature_path, map_location="cpu", weights_only=False)
+                catalog_features[catalog_id] = feats
+            except Exception:
+                # Skip files that can't be loaded
+                continue
+
+    if not catalog_features:
+        raise ValueError(f"No features found for extractor '{extractor}' in catalog")
+
+    return catalog_features
+
+
+def get_filtered_catalog_features(
+    catalog_root: Path,
+    extractor: str = "sift",
+    locations: list[str] | None = None,
+    body_parts: list[str] | None = None,
+) -> dict[str, dict[str, torch.Tensor]]:
+    """Load filtered catalog features for a specific extractor.
+
+    Args:
+        catalog_root: Path to catalog root directory (e.g., data/08_catalog/v1.0/)
+        extractor: Feature extractor name (default: 'sift')
+        locations: List of locations to filter by (e.g., ["skycrest_valley", "silvershadow_highlands"]).
+                   If None, includes all locations.
+        body_parts: List of body parts to filter by (e.g., ["head", "right_flank"]).
+                    If None, includes all body parts.
+
+    Returns:
+        Dictionary mapping catalog_id to feature dict:
+            {
+                "leopard1_2022_001": {
+                    "keypoints": torch.Tensor,
+                    "descriptors": torch.Tensor,
+                    "scores": torch.Tensor,
+                    ...
+                },
+                ...
+            }
+
+    Raises:
+        FileNotFoundError: If catalog doesn't exist
+        ValueError: If no features found for extractor or filters
+    """
+    if not catalog_root.exists():
+        raise FileNotFoundError(f"Catalog root not found: {catalog_root}")
+
+    # Load catalog index to get all individuals
+    index = load_catalog_index(catalog_root)
+
+    # Check if extractor is available
+    available_extractors = index.get("feature_extractors", {})
+    if extractor not in available_extractors:
+        raise ValueError(
+            f"Extractor '{extractor}' not available in catalog. "
+            f"Available: {list(available_extractors.keys())}"
+        )
+
+    catalog_features = {}
+    database_dir = catalog_root / "database"
+
+    # Load features for each individual
+    for individual in index["individuals"]:
+        # Support both 'leopard_name' and 'individual_name' keys
+        leopard_name = individual.get("leopard_name") or individual.get(
+            "individual_name"
+        )
+        location = individual.get("location", "")
+
+        # Filter by location if specified
+        if locations is not None and location not in locations:
+            continue
+
+        # Construct path: database/{location}/{individual_name}/
+        if location:
+            leopard_dir = database_dir / location / leopard_name
+        else:
+            leopard_dir = database_dir / leopard_name
+
+        # Load leopard metadata to get all reference images
+        metadata_path = leopard_dir / "metadata.yaml"
+        metadata = load_leopard_metadata(metadata_path)
+
+        # Load features for each reference image
+        for ref_image in metadata["reference_images"]:
+            # Filter by body part if specified
+            if body_parts is not None:
+                ref_body_part = ref_image.get("body_part", "")
+                if ref_body_part not in body_parts:
+                    continue
+
+            # Check if features exist for this extractor
+            if extractor not in ref_image.get("features", {}):
+                continue
+
+            # Get feature path (relative to database directory in metadata)
+            feature_rel_path = ref_image["features"][extractor]
+            feature_path = database_dir / feature_rel_path
+
+            if not feature_path.exists():
+                # Skip missing features with a warning
+                continue
+
+            # Create catalog ID: leopard_name_year_imagenum
+            # e.g., "naguima_2022_001"
+            image_id = ref_image["image_id"]
+            catalog_id = f"{leopard_name.lower().replace(' ', '_')}_{image_id}"
+
+            # Load features
+            try:
+                feats = torch.load(feature_path, map_location="cpu", weights_only=False)
+                catalog_features[catalog_id] = feats
+            except Exception:
+                # Skip files that can't be loaded
+                continue
+
+    if not catalog_features:
+        filter_info = []
+        if locations:
+            filter_info.append(f"locations={locations}")
+        if body_parts:
+            filter_info.append(f"body_parts={body_parts}")
+        filter_str = ", ".join(filter_info) if filter_info else "no filters"
+        raise ValueError(
+            f"No features found for extractor '{extractor}' with {filter_str}"
+        )
+
+    return catalog_features
+
+
+def get_available_locations(catalog_root: Path) -> list[str]:
+    """Get list of available locations from catalog.
+
+    Args:
+        catalog_root: Path to catalog root directory
+
+    Returns:
+        List of location names prepended with "all" (e.g., ["all", "skycrest_valley", "silvershadow_highlands"])
+    """
+    try:
+        index = load_catalog_index(catalog_root)
+        locations = index.get("statistics", {}).get("locations", [])
+        return ["all"] + sorted(locations)
+    except Exception:
+        return ["all"]
+
+
+def get_available_body_parts(catalog_root: Path) -> list[str]:
+    """Get list of available body parts from catalog.
+
+    Args:
+        catalog_root: Path to catalog root directory
+
+    Returns:
+        List of body part names prepended with "all"
+        (e.g., ["all", "head", "left_flank", "right_flank", "tail", "misc"])
+    """
+    try:
+        index = load_catalog_index(catalog_root)
+        body_parts = index.get("statistics", {}).get("body_parts", [])
+        return ["all"] + sorted(body_parts)
+    except Exception:
+        return ["all"]
+
+
+def get_catalog_metadata_for_id(
+    catalog_root: Path,
+    catalog_id: str,
+) -> dict | None:
+    """Get full metadata for a specific catalog ID.
+
+    Args:
+        catalog_root: Path to catalog root directory
+        catalog_id: Catalog ID (e.g., "naguima_2022_001")
+
+    Returns:
+        Dictionary with metadata including:
+            - leopard_name: str
+            - year: int
+            - image_path: Path
+            - individual_id: str
+        Or None if not found
+
+    Raises:
+        FileNotFoundError: If catalog doesn't exist
+    """
+    if not catalog_root.exists():
+        raise FileNotFoundError(f"Catalog root not found: {catalog_root}")
+
+    # Load catalog index
+    index = load_catalog_index(catalog_root)
+    database_dir = catalog_root / "database"
+
+    # Try to find matching individual
+    for individual in index["individuals"]:
+        # Support both 'leopard_name' and 'individual_name' keys
+        leopard_name = individual.get("leopard_name") or individual.get(
+            "individual_name"
+        )
+        location = individual.get("location", "")
+
+        # Construct path: database/{location}/{individual_name}/
+        if location:
+            leopard_dir = database_dir / location / leopard_name
+        else:
+            leopard_dir = database_dir / leopard_name
+
+        # Load leopard metadata
+        metadata_path = leopard_dir / "metadata.yaml"
+        metadata = load_leopard_metadata(metadata_path)
+
+        # Check each reference image
+        for ref_image in metadata["reference_images"]:
+            # Construct expected catalog ID
+            image_id = ref_image["image_id"]
+            expected_id = f"{leopard_name.lower().replace(' ', '_')}_{image_id}"
+
+            if expected_id == catalog_id:
+                # Found match
+                return {
+                    "leopard_name": leopard_name,
+                    "image_path": database_dir / ref_image["path"],
+                    "individual_id": metadata["individual_id"],
+                    "filename": ref_image["filename"],
+                }
+
+    return None

src/snowleopard_reid/data_setup.py

@@ -0,0 +1,102 @@
+"""Data setup utilities for extracting archives on first run.
+
+This module handles the extraction of catalog and cache archives when the
+application starts. Archives are extracted only once, on first run.
+"""
+
+import logging
+import tarfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Paths relative to project root
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+DATA_DIR = PROJECT_ROOT / "data"
+CATALOG_ARCHIVE = DATA_DIR / "catalog.tar.gz"
+CATALOG_DIR = DATA_DIR / "catalog"
+CACHE_ARCHIVE = DATA_DIR / "cache.tar.gz"
+CACHE_DIR = PROJECT_ROOT / "cached_results"
+
+
+def extract_archive(archive_path: Path, extract_to: Path) -> bool:
+    """Extract a tar.gz archive to specified directory.
+
+    Args:
+        archive_path: Path to the .tar.gz archive
+        extract_to: Directory to extract to (parent of archived dir)
+
+    Returns:
+        True if extraction successful, False otherwise
+    """
+    if not archive_path.exists():
+        logger.debug(f"Archive not found: {archive_path}")
+        return False
+
+    try:
+        logger.info(f"Extracting {archive_path.name}...")
+        extract_to.mkdir(parents=True, exist_ok=True)
+
+        with tarfile.open(archive_path, "r:gz") as tar:
+            tar.extractall(path=extract_to)
+
+        logger.info(f"Extracted {archive_path.name} successfully")
+        return True
+
+    except Exception as e:
+        logger.error(f"Failed to extract {archive_path.name}: {e}")
+        return False
+
+
+def ensure_data_extracted() -> None:
+    """Ensure catalog and cache archives are extracted.
+
+    Call this function at application startup. It will:
+    - Check if catalog directory exists, extract from archive if not
+    - Check if cache directory exists, extract from archive if not
+
+    Archives are only extracted if:
+    1. The archive file exists
+    2. The target directory does not exist
+
+    This makes the function idempotent - safe to call multiple times.
+    """
+    # Extract catalog if needed
+    if CATALOG_ARCHIVE.exists() and not CATALOG_DIR.exists():
+        logger.info("First run detected - extracting catalog data...")
+        extract_archive(CATALOG_ARCHIVE, DATA_DIR)
+
+    # Extract cache if needed
+    if CACHE_ARCHIVE.exists() and not CACHE_DIR.exists():
+        logger.info("First run detected - extracting cached results...")
+        extract_archive(CACHE_ARCHIVE, PROJECT_ROOT)
+
+    # Log status
+    catalog_ready = CATALOG_DIR.exists()
+    cache_ready = CACHE_DIR.exists()
+
+    if catalog_ready and cache_ready:
+        logger.debug("All data directories ready")
+    else:
+        if not catalog_ready:
+            logger.warning(f"Catalog not available: {CATALOG_DIR}")
+        if not cache_ready:
+            logger.warning(f"Cache not available: {CACHE_DIR}")
+
+
+def is_data_ready() -> bool:
+    """Check if all required data directories exist.
+
+    Returns:
+        True if catalog directory exists, False otherwise
+    """
+    return CATALOG_DIR.exists()
+
+
+def is_cache_ready() -> bool:
+    """Check if cache directory exists.
+
+    Returns:
+        True if cache directory exists, False otherwise
+    """
+    return CACHE_DIR.exists()

src/snowleopard_reid/features/__init__.py

@@ -0,0 +1,27 @@
+"""Features module for snow leopard re-identification.
+
+This module provides utilities for extracting, loading, and saving features
+from snow leopard images using various feature extractors (SIFT, SuperPoint, DISK, ALIKED).
+"""
+
+from .extraction import (
+    extract_aliked_features,
+    extract_disk_features,
+    extract_features,
+    extract_sift_features,
+    extract_superpoint_features,
+    get_num_keypoints,
+    load_features,
+    save_features,
+)
+
+__all__ = [
+    "extract_features",
+    "extract_sift_features",
+    "extract_superpoint_features",
+    "extract_disk_features",
+    "extract_aliked_features",
+    "load_features",
+    "save_features",
+    "get_num_keypoints",
+]

src/snowleopard_reid/features/extraction.py

@@ -0,0 +1,388 @@
+"""Utilities for feature extraction and management.
+
+This module provides functions for extracting, loading, and saving image features
+using various feature extractors (SIFT, SuperPoint, DISK, ALIKED).
+"""
+
+from pathlib import Path
+
+import torch
+from lightglue import ALIKED, DISK, SIFT, SuperPoint
+from lightglue.utils import load_image, rbd
+from PIL import Image
+
+
+def extract_sift_features(
+    image_path: Path | str | Image.Image,
+    max_num_keypoints: int = 2048,
+    device: str = "cpu",
+) -> dict[str, torch.Tensor]:
+    """Extract SIFT features from an image.
+
+    Args:
+        image_path: Path to image file or PIL Image object
+        max_num_keypoints: Maximum number of keypoints to extract (default: 2048, range: 512-4096)
+        device: Device to run extraction on ('cpu' or 'cuda')
+
+    Returns:
+        Dictionary with keys:
+            - keypoints: Tensor of shape [N, 2] with (x, y) coordinates
+            - descriptors: Tensor of shape [N, 128] with SIFT descriptors
+            - scores: Tensor of shape [N] with keypoint scores
+            - image_size: Tensor of shape [2] with (width, height)
+
+    Raises:
+        ValueError: If max_num_keypoints is out of valid range
+        FileNotFoundError: If image_path is a string/Path and file doesn't exist
+    """
+    # Validate parameters
+    if not (512 <= max_num_keypoints <= 4096):
+        raise ValueError(
+            f"max_num_keypoints must be in range 512-4096, got {max_num_keypoints}"
+        )
+
+    # Initialize extractor
+    extractor = SIFT(max_num_keypoints=max_num_keypoints).eval().to(device)
+
+    # Load image
+    if isinstance(image_path, (str, Path)):
+        image_path = Path(image_path)
+        if not image_path.exists():
+            raise FileNotFoundError(f"Image not found: {image_path}")
+        # load_image returns torch.Tensor [3, H, W]
+        image = load_image(str(image_path))
+    elif isinstance(image_path, Image.Image):
+        # Convert PIL Image to path temporarily
+        # For now, require path input for lightglue compatibility
+        raise TypeError(
+            "PIL Image input not yet supported, please provide path to image file"
+        )
+    else:
+        raise TypeError(
+            f"image_path must be str, Path, or PIL Image, got {type(image_path)}"
+        )
+
+    # Move image to device
+    image = image.to(device)
+
+    # Extract features
+    with torch.no_grad():
+        feats = extractor.extract(image)  # auto-resizes image
+        feats = rbd(feats)  # remove batch dimension
+
+    # Move features back to CPU for storage
+    if device != "cpu":
+        feats = {
+            k: v.cpu() if isinstance(v, torch.Tensor) else v for k, v in feats.items()
+        }
+
+    return feats
+
+
+def extract_superpoint_features(
+    image_path: Path | str | Image.Image,
+    max_num_keypoints: int = 2048,
+    device: str = "cpu",
+) -> dict[str, torch.Tensor]:
+    """Extract SuperPoint features from an image.
+
+    Args:
+        image_path: Path to image file or PIL Image object
+        max_num_keypoints: Maximum number of keypoints to extract (default: 2048, range: 512-4096)
+        device: Device to run extraction on ('cpu' or 'cuda')
+
+    Returns:
+        Dictionary with keys:
+            - keypoints: Tensor of shape [N, 2] with (x, y) coordinates
+            - descriptors: Tensor of shape [N, 256] with SuperPoint descriptors
+            - scores: Tensor of shape [N] with keypoint scores
+            - image_size: Tensor of shape [2] with (width, height)
+
+    Raises:
+        ValueError: If max_num_keypoints is out of valid range
+        FileNotFoundError: If image_path is a string/Path and file doesn't exist
+    """
+    # Validate parameters
+    if not (512 <= max_num_keypoints <= 4096):
+        raise ValueError(
+            f"max_num_keypoints must be in range 512-4096, got {max_num_keypoints}"
+        )
+
+    # Initialize extractor
+    extractor = SuperPoint(max_num_keypoints=max_num_keypoints).eval().to(device)
+
+    # Load image
+    if isinstance(image_path, (str, Path)):
+        image_path = Path(image_path)
+        if not image_path.exists():
+            raise FileNotFoundError(f"Image not found: {image_path}")
+        image = load_image(str(image_path))
+    elif isinstance(image_path, Image.Image):
+        raise TypeError(
+            "PIL Image input not yet supported, please provide path to image file"
+        )
+    else:
+        raise TypeError(
+            f"image_path must be str, Path, or PIL Image, got {type(image_path)}"
+        )
+
+    # Move image to device
+    image = image.to(device)
+
+    # Extract features
+    with torch.no_grad():
+        feats = extractor.extract(image)
+        feats = rbd(feats)  # remove batch dimension
+
+    # Move features back to CPU for storage
+    if device != "cpu":
+        feats = {
+            k: v.cpu() if isinstance(v, torch.Tensor) else v for k, v in feats.items()
+        }
+
+    return feats
+
+
+def extract_disk_features(
+    image_path: Path | str | Image.Image,
+    max_num_keypoints: int = 2048,
+    device: str = "cpu",
+) -> dict[str, torch.Tensor]:
+    """Extract DISK features from an image.
+
+    Args:
+        image_path: Path to image file or PIL Image object
+        max_num_keypoints: Maximum number of keypoints to extract (default: 2048, range: 512-4096)
+        device: Device to run extraction on ('cpu' or 'cuda')
+
+    Returns:
+        Dictionary with keys:
+            - keypoints: Tensor of shape [N, 2] with (x, y) coordinates
+            - descriptors: Tensor of shape [N, 128] with DISK descriptors
+            - scores: Tensor of shape [N] with keypoint scores
+            - image_size: Tensor of shape [2] with (width, height)
+
+    Raises:
+        ValueError: If max_num_keypoints is out of valid range
+        FileNotFoundError: If image_path is a string/Path and file doesn't exist
+    """
+    # Validate parameters
+    if not (512 <= max_num_keypoints <= 4096):
+        raise ValueError(
+            f"max_num_keypoints must be in range 512-4096, got {max_num_keypoints}"
+        )
+
+    # Initialize extractor
+    extractor = DISK(max_num_keypoints=max_num_keypoints).eval().to(device)
+
+    # Load image
+    if isinstance(image_path, (str, Path)):
+        image_path = Path(image_path)
+        if not image_path.exists():
+            raise FileNotFoundError(f"Image not found: {image_path}")
+        image = load_image(str(image_path))
+    elif isinstance(image_path, Image.Image):
+        raise TypeError(
+            "PIL Image input not yet supported, please provide path to image file"
+        )
+    else:
+        raise TypeError(
+            f"image_path must be str, Path, or PIL Image, got {type(image_path)}"
+        )
+
+    # Move image to device
+    image = image.to(device)
+
+    # Extract features
+    with torch.no_grad():
+        feats = extractor.extract(image)
+        feats = rbd(feats)  # remove batch dimension
+
+    # Move features back to CPU for storage
+    if device != "cpu":
+        feats = {
+            k: v.cpu() if isinstance(v, torch.Tensor) else v for k, v in feats.items()
+        }
+
+    return feats
+
+
+def extract_aliked_features(
+    image_path: Path | str | Image.Image,
+    max_num_keypoints: int = 2048,
+    device: str = "cpu",
+) -> dict[str, torch.Tensor]:
+    """Extract ALIKED features from an image.
+
+    Args:
+        image_path: Path to image file or PIL Image object
+        max_num_keypoints: Maximum number of keypoints to extract (default: 2048, range: 512-4096)
+        device: Device to run extraction on ('cpu' or 'cuda')
+
+    Returns:
+        Dictionary with keys:
+            - keypoints: Tensor of shape [N, 2] with (x, y) coordinates
+            - descriptors: Tensor of shape [N, 128] with ALIKED descriptors
+            - scores: Tensor of shape [N] with keypoint scores
+            - image_size: Tensor of shape [2] with (width, height)
+
+    Raises:
+        ValueError: If max_num_keypoints is out of valid range
+        FileNotFoundError: If image_path is a string/Path and file doesn't exist
+    """
+    # Validate parameters
+    if not (512 <= max_num_keypoints <= 4096):
+        raise ValueError(
+            f"max_num_keypoints must be in range 512-4096, got {max_num_keypoints}"
+        )
+
+    # Initialize extractor
+    extractor = ALIKED(max_num_keypoints=max_num_keypoints).eval().to(device)
+
+    # Load image
+    if isinstance(image_path, (str, Path)):
+        image_path = Path(image_path)
+        if not image_path.exists():
+            raise FileNotFoundError(f"Image not found: {image_path}")
+        image = load_image(str(image_path))
+    elif isinstance(image_path, Image.Image):
+        raise TypeError(
+            "PIL Image input not yet supported, please provide path to image file"
+        )
+    else:
+        raise TypeError(
+            f"image_path must be str, Path, or PIL Image, got {type(image_path)}"
+        )
+
+    # Move image to device
+    image = image.to(device)
+
+    # Extract features
+    with torch.no_grad():
+        feats = extractor.extract(image)
+        feats = rbd(feats)  # remove batch dimension
+
+    # Move features back to CPU for storage
+    if device != "cpu":
+        feats = {
+            k: v.cpu() if isinstance(v, torch.Tensor) else v for k, v in feats.items()
+        }
+
+    return feats
+
+
+def load_features(features_path: Path | str) -> dict[str, torch.Tensor]:
+    """Load features from a PyTorch .pt file.
+
+    Args:
+        features_path: Path to .pt file containing features
+
+    Returns:
+        Dictionary with feature tensors (keypoints, descriptors, scores, etc.)
+
+    Raises:
+        FileNotFoundError: If features file doesn't exist
+        RuntimeError: If file cannot be loaded
+    """
+    features_path = Path(features_path)
+
+    if not features_path.exists():
+        raise FileNotFoundError(f"Features file not found: {features_path}")
+
+    try:
+        feats = torch.load(features_path, map_location="cpu", weights_only=False)
+        return feats
+    except Exception as e:
+        raise RuntimeError(f"Failed to load features from {features_path}: {e}")
+
+
+def save_features(
+    features: dict[str, torch.Tensor],
+    output_path: Path | str,
+    create_dirs: bool = True,
+) -> None:
+    """Save features to a PyTorch .pt file.
+
+    Args:
+        features: Dictionary with feature tensors to save
+        output_path: Path where to save .pt file
+        create_dirs: Whether to create parent directories if they don't exist
+
+    Raises:
+        ValueError: If features dict is empty or invalid
+        OSError: If directory creation or file writing fails
+    """
+    if not features:
+        raise ValueError("Features dictionary is empty")
+
+    output_path = Path(output_path)
+
+    # Create parent directories if needed
+    if create_dirs and not output_path.parent.exists():
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        torch.save(features, output_path)
+    except Exception as e:
+        raise OSError(f"Failed to save features to {output_path}: {e}")
+
+
+def get_num_keypoints(features: dict[str, torch.Tensor]) -> int:
+    """Get the number of keypoints from a features dictionary.
+
+    Args:
+        features: Dictionary with 'keypoints' tensor
+
+    Returns:
+        Number of keypoints (first dimension of keypoints tensor)
+
+    Raises:
+        KeyError: If 'keypoints' key is missing
+    """
+    if "keypoints" not in features:
+        raise KeyError("Features dictionary missing 'keypoints' key")
+
+    return features["keypoints"].shape[0]
+
+
+def extract_features(
+    extractor: str,
+    image_path: Path | str | Image.Image,
+    max_num_keypoints: int = 2048,
+    device: str = "cpu",
+) -> dict[str, torch.Tensor]:
+    """Extract features from an image using the specified extractor.
+
+    Factory function that dispatches to the appropriate feature extractor.
+
+    Args:
+        extractor: Feature extractor name ('sift', 'superpoint', 'disk', 'aliked')
+        image_path: Path to image file or PIL Image object
+        max_num_keypoints: Maximum number of keypoints to extract (default: 2048)
+        device: Device to run extraction on ('cpu' or 'cuda')
+
+    Returns:
+        Dictionary with feature tensors (keypoints, descriptors, scores, image_size)
+
+    Raises:
+        ValueError: If extractor name is not supported
+        FileNotFoundError: If image_path is a string/Path and file doesn't exist
+
+    Examples:
+        >>> features = extract_features("sift", "image.jpg")
+        >>> features = extract_features("sift", "image.jpg", max_num_keypoints=4096, device="cuda")
+    """
+    extractor = extractor.lower()
+
+    if extractor == "sift":
+        return extract_sift_features(image_path, max_num_keypoints, device)
+    elif extractor == "superpoint":
+        return extract_superpoint_features(image_path, max_num_keypoints, device)
+    elif extractor == "disk":
+        return extract_disk_features(image_path, max_num_keypoints, device)
+    elif extractor == "aliked":
+        return extract_aliked_features(image_path, max_num_keypoints, device)
+    else:
+        raise ValueError(
+            f"Unsupported extractor: {extractor}. Supported extractors: sift, superpoint, disk, aliked"
+        )

src/snowleopard_reid/images/__init__.py

@@ -0,0 +1,13 @@
+"""Image processing utilities for the Snow Leopard Re-ID project."""
+
+from snowleopard_reid.images.processing import (
+    resize_image_if_needed,
+    resize_image_if_needed_cv2,
+    resize_image_if_needed_pil,
+)
+
+__all__ = [
+    "resize_image_if_needed",
+    "resize_image_if_needed_cv2",
+    "resize_image_if_needed_pil",
+]

src/snowleopard_reid/images/processing.py

@@ -0,0 +1,93 @@
+"""Image processing utilities for the Snow Leopard Re-ID project."""
+
+import logging
+
+import cv2
+import numpy as np
+from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+def resize_image_if_needed_pil(image: Image.Image, max_dim: int = 1024) -> Image.Image:
+    """
+    Resize PIL Image if either dimension exceeds max_dim, maintaining aspect ratio.
+
+    Args:
+        image: PIL Image to resize
+        max_dim: Maximum allowed dimension (default: 1024)
+
+    Returns:
+        Resized image (or original if no resize needed)
+    """
+    width, height = image.size
+
+    if width <= max_dim and height <= max_dim:
+        return image
+
+    # Calculate scaling factor
+    scale = min(max_dim / width, max_dim / height)
+
+    # Calculate new dimensions
+    new_width = int(width * scale)
+    new_height = int(height * scale)
+
+    # Resize image using high-quality LANCZOS filter
+    resized = image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+    logger.debug(f"Resized image from {width}x{height} to {new_width}x{new_height}")
+
+    return resized
+
+
+def resize_image_if_needed_cv2(img: np.ndarray, max_dim: int = 1024) -> np.ndarray:
+    """
+    Resize cv2 image if either dimension exceeds max_dim, maintaining aspect ratio.
+
+    Args:
+        img: Input image as numpy array
+        max_dim: Maximum allowed dimension (default: 1024)
+
+    Returns:
+        Resized image (or original if no resize needed)
+    """
+    height, width = img.shape[:2]
+
+    if height <= max_dim and width <= max_dim:
+        return img
+
+    # Calculate scaling factor
+    scale = min(max_dim / height, max_dim / width)
+
+    # Calculate new dimensions
+    new_width = int(width * scale)
+    new_height = int(height * scale)
+
+    # Resize image using INTER_AREA (best for downscaling)
+    resized = cv2.resize(img, (new_width, new_height), interpolation=cv2.INTER_AREA)
+    logger.debug(f"Resized image from {width}x{height} to {new_width}x{new_height}")
+
+    return resized
+
+
+def resize_image_if_needed(
+    image: Image.Image | np.ndarray, max_dim: int = 1024
+) -> Image.Image | np.ndarray:
+    """
+    Resize image if either dimension exceeds max_dim, maintaining aspect ratio.
+
+    Automatically detects whether the input is a PIL Image or numpy array
+    and applies the appropriate resize function.
+
+    Args:
+        image: PIL Image or numpy array to resize
+        max_dim: Maximum allowed dimension (default: 1024)
+
+    Returns:
+        Resized image (or original if no resize needed)
+    """
+    if isinstance(image, Image.Image):
+        return resize_image_if_needed_pil(image=image, max_dim=max_dim)
+    elif isinstance(image, np.ndarray):
+        return resize_image_if_needed_cv2(img=image, max_dim=max_dim)
+    else:
+        raise TypeError(f"Expected PIL.Image.Image or np.ndarray, got {type(image)}")

src/snowleopard_reid/masks/__init__.py

@@ -0,0 +1,13 @@
+"""Mask processing utilities for snow leopard re-identification."""
+
+from snowleopard_reid.masks.processing import (
+    add_padding_to_bbox,
+    crop_and_mask_image,
+    get_mask_bbox,
+)
+
+__all__ = [
+    "get_mask_bbox",
+    "add_padding_to_bbox",
+    "crop_and_mask_image",
+]

src/snowleopard_reid/masks/processing.py

@@ -0,0 +1,99 @@
+"""Utilities for mask processing and image cropping.
+
+This module provides functions for working with binary segmentation masks,
+calculating bounding boxes, and cropping images with masks applied.
+"""
+
+import numpy as np
+from PIL import Image
+
+
+def get_mask_bbox(mask: np.ndarray) -> tuple[int, int, int, int]:
+    """Calculate the tight bounding box of a binary mask.
+
+    Args:
+        mask: Binary mask array (0=background, 255=foreground)
+
+    Returns:
+        Tuple of (x_min, y_min, x_max, y_max) in pixel coordinates
+
+    Raises:
+        ValueError: If mask is empty (no foreground pixels)
+    """
+    # Find all pixels that are part of the mask
+    rows = np.any(mask > 0, axis=1)
+    cols = np.any(mask > 0, axis=0)
+
+    if not np.any(rows) or not np.any(cols):
+        raise ValueError("Mask is empty (no foreground pixels)")
+
+    y_min, y_max = np.where(rows)[0][[0, -1]]
+    x_min, x_max = np.where(cols)[0][[0, -1]]
+
+    return int(x_min), int(y_min), int(x_max), int(y_max)
+
+
+def add_padding_to_bbox(
+    bbox: tuple[int, int, int, int],
+    padding: int,
+    image_width: int,
+    image_height: int,
+) -> tuple[int, int, int, int]:
+    """Add padding to a bounding box, clamped to image boundaries.
+
+    Args:
+        bbox: Original bounding box (x_min, y_min, x_max, y_max)
+        padding: Padding in pixels to add on all sides
+        image_width: Image width for clamping
+        image_height: Image height for clamping
+
+    Returns:
+        Padded bounding box (x_min, y_min, x_max, y_max)
+    """
+    x_min, y_min, x_max, y_max = bbox
+
+    x_min = max(0, x_min - padding)
+    y_min = max(0, y_min - padding)
+    x_max = min(image_width - 1, x_max + padding)
+    y_max = min(image_height - 1, y_max + padding)
+
+    return x_min, y_min, x_max, y_max
+
+
+def crop_and_mask_image(
+    image: Image.Image,
+    mask: np.ndarray,
+    bbox: tuple[int, int, int, int],
+) -> Image.Image:
+    """Crop image to bbox and apply mask with black background.
+
+    Args:
+        image: Original PIL Image
+        mask: Binary mask array (same size as image, 0=background, 255=foreground)
+        bbox: Bounding box to crop to (x_min, y_min, x_max, y_max)
+
+    Returns:
+        Cropped and masked PIL Image with black background
+    """
+    x_min, y_min, x_max, y_max = bbox
+
+    # Crop image and mask to bounding box
+    cropped_image = image.crop((x_min, y_min, x_max + 1, y_max + 1))
+    cropped_mask = mask[y_min : y_max + 1, x_min : x_max + 1]
+
+    # Convert image to numpy array
+    image_array = np.array(cropped_image)
+
+    # Create mask with correct shape (add channel dimension if needed)
+    if len(image_array.shape) == 3:
+        # RGB image - expand mask to 3 channels
+        mask_3d = np.repeat(cropped_mask[:, :, np.newaxis] > 0, 3, axis=2)
+    else:
+        # Grayscale image
+        mask_3d = cropped_mask > 0
+
+    # Apply mask: keep original pixels where mask is True, black elsewhere
+    masked_array = np.where(mask_3d, image_array, 0)
+
+    # Convert back to PIL Image
+    return Image.fromarray(masked_array.astype(np.uint8))

src/snowleopard_reid/pipeline/__init__.py

@@ -0,0 +1,23 @@
+"""Pipeline module for snow leopard re-identification.
+
+This module provides the complete end-to-end pipeline for identifying individual
+snow leopards from query images.
+"""
+
+from .stages import (
+    run_feature_extraction_stage,
+    run_mask_selection_stage,
+    run_matching_stage,
+    run_preprocess_stage,
+    run_segmentation_stage,
+    select_best_mask,
+)
+
+__all__ = [
+    "run_segmentation_stage",
+    "run_mask_selection_stage",
+    "run_preprocess_stage",
+    "run_feature_extraction_stage",
+    "run_matching_stage",
+    "select_best_mask",
+]

src/snowleopard_reid/pipeline/stages/__init__.py

@@ -0,0 +1,20 @@
+"""Pipeline stages for snow leopard re-identification.
+
+This module contains all pipeline stages that process query images through
+segmentation, feature extraction, and matching.
+"""
+
+from .feature_extraction import run_feature_extraction_stage
+from .mask_selection import run_mask_selection_stage, select_best_mask
+from .matching import run_matching_stage
+from .preprocess import run_preprocess_stage
+from .segmentation import run_segmentation_stage
+
+__all__ = [
+    "run_segmentation_stage",
+    "run_mask_selection_stage",
+    "select_best_mask",
+    "run_preprocess_stage",
+    "run_feature_extraction_stage",
+    "run_matching_stage",
+]

src/snowleopard_reid/pipeline/stages/feature_extraction.py

@@ -0,0 +1,134 @@
+"""Feature extraction stage for query images.
+
+This module extracts features from cropped query images for matching
+against the catalog.
+"""
+
+import logging
+import tempfile
+from pathlib import Path
+
+import torch
+from PIL import Image
+
+from snowleopard_reid import features, get_device
+
+logger = logging.getLogger(__name__)
+
+
+def run_feature_extraction_stage(
+    image: Image.Image | Path | str,
+    extractor: str = "sift",
+    max_keypoints: int = 2048,
+    device: str | None = None,
+) -> dict:
+    """Extract features from query image.
+
+    This stage extracts keypoints and descriptors from the preprocessed query
+    image using the specified feature extractor.
+
+    Args:
+        image: PIL Image object or path to image file
+        extractor: Feature extractor to use (default: 'sift')
+        max_keypoints: Maximum number of keypoints to extract (default: 2048)
+        device: Device to run on ('cpu', 'cuda', or None for auto-detect)
+
+    Returns:
+        Stage dict with structure:
+        {
+            "stage_id": "feature_extraction",
+            "stage_name": "Feature Extraction",
+            "description": "Extract keypoints and descriptors",
+            "config": {
+                "extractor": str,
+                "max_keypoints": int,
+                "device": str
+            },
+            "metrics": {
+                "num_keypoints": int
+            },
+            "data": {
+                "features": {
+                    "keypoints": torch.Tensor [N, 2],
+                    "descriptors": torch.Tensor [N, D],
+                    "scores": torch.Tensor [N],
+                    "image_size": torch.Tensor [2]
+                }
+            }
+        }
+
+    Raises:
+        ValueError: If extractor is not supported
+        FileNotFoundError: If image path doesn't exist
+        RuntimeError: If feature extraction fails
+    """
+    # Auto-detect device if not specified
+    device = get_device(device=device, verbose=True)
+
+    # Extract features using the factory function
+    features_dict = _extract_features_from_image(
+        image=image, extractor=extractor, max_keypoints=max_keypoints, device=device
+    )
+
+    # Get number of keypoints
+    num_kpts = features.get_num_keypoints(features_dict)
+    logger.info(f"Extracted {num_kpts} keypoints using {extractor.upper()}")
+
+    # Return standardized stage dict
+    return {
+        "stage_id": "feature_extraction",
+        "stage_name": "Feature Extraction",
+        "description": "Extract keypoints and descriptors",
+        "config": {
+            "extractor": extractor,
+            "max_keypoints": max_keypoints,
+            "device": device,
+        },
+        "metrics": {
+            "num_keypoints": num_kpts,
+        },
+        "data": {
+            "features": features_dict,
+        },
+    }
+
+
+def _extract_features_from_image(
+    image: Image.Image | Path | str,
+    extractor: str,
+    max_keypoints: int,
+    device: str,
+) -> dict[str, torch.Tensor]:
+    """Extract features from PIL Image or path using specified extractor.
+
+    This is a wrapper that handles PIL Image input by saving to a temporary file,
+    since lightglue's load_image() requires a file path.
+
+    Args:
+        image: PIL Image or path to image
+        extractor: Feature extractor to use ('sift', 'superpoint', 'disk', 'aliked')
+        max_keypoints: Maximum keypoints to extract
+        device: Device to use
+
+    Returns:
+        Features dictionary
+    """
+    if isinstance(image, Image.Image):
+        # Save PIL Image to temporary file
+        with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
+            tmp_path = Path(tmp.name)
+            image.save(tmp_path, quality=95)
+
+        try:
+            # Extract features from temporary file
+            feats = features.extract_features(
+                extractor, tmp_path, max_keypoints, device
+            )
+        finally:
+            # Clean up temporary file
+            tmp_path.unlink()
+
+        return feats
+    else:
+        # Image is already a path
+        return features.extract_features(extractor, image, max_keypoints, device)

src/snowleopard_reid/pipeline/stages/mask_selection.py

@@ -0,0 +1,153 @@
+"""Mask selection stage for choosing the best snow leopard mask.
+
+This module provides logic for selecting the best mask from multiple YOLO predictions.
+"""
+
+import logging
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def select_best_mask(
+    predictions: list[dict],
+    strategy: str = "confidence_area",
+) -> tuple[int, dict]:
+    """Select the best mask from predictions using specified strategy.
+
+    Args:
+        predictions: List of prediction dicts from YOLO segmentation stage
+        strategy: Selection strategy ('confidence_area', 'confidence', 'area', 'center')
+
+    Returns:
+        Tuple of (selected_index, selected_prediction)
+
+    Raises:
+        ValueError: If predictions list is empty or strategy is invalid
+    """
+    if not predictions:
+        raise ValueError("Predictions list is empty")
+
+    valid_strategies = ["confidence_area", "confidence", "area", "center"]
+    if strategy not in valid_strategies:
+        raise ValueError(
+            f"Invalid strategy '{strategy}'. Valid strategies: {valid_strategies}"
+        )
+
+    if strategy == "confidence_area":
+        # Select mask with highest confidence * area product
+        scores = []
+        for pred in predictions:
+            confidence = pred["confidence"]
+            mask = pred["mask"]
+            area = np.sum(mask > 0)
+            scores.append(confidence * area)
+        selected_idx = int(np.argmax(scores))
+
+    elif strategy == "confidence":
+        # Select mask with highest confidence
+        confidences = [pred["confidence"] for pred in predictions]
+        selected_idx = int(np.argmax(confidences))
+
+    elif strategy == "area":
+        # Select mask with largest area
+        areas = [np.sum(pred["mask"] > 0) for pred in predictions]
+        selected_idx = int(np.argmax(areas))
+
+    elif strategy == "center":
+        # Select mask closest to image center
+        # This strategy requires image size, which we can get from bbox
+        distances = []
+        for pred in predictions:
+            bbox = pred["bbox_xywhn"]
+            # Center is already normalized to [0, 1]
+            x_center = bbox["x_center"]
+            y_center = bbox["y_center"]
+            # Distance from image center (0.5, 0.5)
+            dist = np.sqrt((x_center - 0.5) ** 2 + (y_center - 0.5) ** 2)
+            distances.append(dist)
+        selected_idx = int(np.argmin(distances))
+
+    return selected_idx, predictions[selected_idx]
+
+
+def run_mask_selection_stage(
+    predictions: list[dict],
+    strategy: str = "confidence_area",
+) -> dict:
+    """Run mask selection stage.
+
+    This stage selects the best mask from multiple YOLO predictions using
+    the specified selection strategy.
+
+    Args:
+        predictions: List of prediction dicts from segmentation stage
+        strategy: Selection strategy (default: 'confidence_area')
+
+    Returns:
+        Stage dict with structure:
+        {
+            "stage_id": "mask_selection",
+            "stage_name": "Mask Selection",
+            "description": "Select best mask from predictions",
+            "config": {
+                "strategy": str
+            },
+            "metrics": {
+                "num_candidates": int,
+                "selected_index": int,
+                "selected_confidence": float
+            },
+            "data": {
+                "selected_prediction": dict,
+                "metadata": {
+                    "strategy": str,
+                    "selected_index": int,
+                    "num_candidates": int,
+                    "confidence": float,
+                    "mask_area": int
+                }
+            }
+        }
+
+    Raises:
+        ValueError: If predictions list is empty
+    """
+    logger.info(f"Selecting best mask using strategy: {strategy}")
+
+    # Select best mask
+    selected_idx, selected_pred = select_best_mask(predictions, strategy)
+
+    # Compute metadata
+    mask_area = int(np.sum(selected_pred["mask"] > 0))
+    confidence = selected_pred["confidence"]
+
+    logger.info(
+        f"Selected mask {selected_idx} (confidence={confidence:.3f}, area={mask_area})"
+    )
+
+    # Return standardized stage dict
+    return {
+        "stage_id": "mask_selection",
+        "stage_name": "Mask Selection",
+        "description": "Select best mask from predictions",
+        "config": {
+            "strategy": strategy,
+        },
+        "metrics": {
+            "num_candidates": len(predictions),
+            "selected_index": selected_idx,
+            "selected_confidence": confidence,
+        },
+        "data": {
+            "selected_prediction": selected_pred,
+            "metadata": {
+                "strategy": strategy,
+                "selected_index": selected_idx,
+                "num_candidates": len(predictions),
+                "confidence": confidence,
+                "mask_area": mask_area,
+            },
+        },
+    }

src/snowleopard_reid/pipeline/stages/matching.py

@@ -0,0 +1,593 @@
+"""Matching stage for snow leopard identification.
+
+This module handles matching query features against the catalog using
+LightGlue and computing matching metrics.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+from lightglue import LightGlue
+from scipy.stats import wasserstein_distance
+
+from snowleopard_reid import get_device
+from snowleopard_reid.catalog import (
+    get_all_catalog_features,
+    get_catalog_metadata_for_id,
+    get_filtered_catalog_features,
+    load_catalog_index,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def run_matching_stage(
+    query_features: dict[str, torch.Tensor],
+    catalog_path: Path | str,
+    top_k: int = 5,
+    extractor: str = "sift",
+    device: str | None = None,
+    query_image_path: str | None = None,
+    pairwise_output_dir: Path | None = None,
+    filter_locations: list[str] | None = None,
+    filter_body_parts: list[str] | None = None,
+) -> dict:
+    """Match query against catalog.
+
+    This stage matches the query features against all catalog images using
+    LightGlue, computes metrics, and ranks matches.
+
+    Args:
+        query_features: Query features dict with keypoints, descriptors, scores
+        catalog_path: Path to catalog root directory (e.g., data/08_catalog/v1.0/)
+        top_k: Number of top matches to return (default: 5)
+        extractor: Feature extractor used (default: 'sift')
+        device: Device to run matching on ('cpu', 'cuda', or None for auto-detect)
+        query_image_path: Path to query image (optional, for pairwise data)
+        pairwise_output_dir: Directory to save pairwise match data (optional)
+        filter_locations: List of locations to filter catalog by (e.g., ["skycrest_valley"])
+        filter_body_parts: List of body parts to filter catalog by (e.g., ["head", "right_flank"])
+
+    Returns:
+        Stage dict with structure:
+        {
+            "stage_id": "matching",
+            "stage_name": "Matching",
+            "description": "Match query against catalog using LightGlue",
+            "config": {...},
+            "metrics": {...},
+            "data": {
+                "catalog_info": {...},
+                "matches": [...]
+            }
+        }
+
+    Raises:
+        FileNotFoundError: If catalog doesn't exist
+        ValueError: If extractor not available in catalog
+        RuntimeError: If matching fails
+    """
+    catalog_path = Path(catalog_path)
+
+    if not catalog_path.exists():
+        raise FileNotFoundError(f"Catalog not found: {catalog_path}")
+
+    # Auto-detect device
+    device = get_device(device=device, verbose=True)
+
+    # Load catalog index
+    logger.info(f"Loading catalog from {catalog_path}")
+    catalog_index = load_catalog_index(catalog_path)
+    logger.info(
+        f"Catalog v{catalog_index['catalog_version']}: "
+        f"{catalog_index['statistics']['total_individuals']} individuals, "
+        f"{catalog_index['statistics']['total_reference_images']} images"
+    )
+
+    # Load catalog features (with optional filtering)
+    if filter_locations or filter_body_parts:
+        filter_info = []
+        if filter_locations:
+            filter_info.append(f"locations={filter_locations}")
+        if filter_body_parts:
+            filter_info.append(f"body_parts={filter_body_parts}")
+        logger.info(f"Loading filtered catalog features ({', '.join(filter_info)})")
+        try:
+            catalog_features = get_filtered_catalog_features(
+                catalog_root=catalog_path,
+                extractor=extractor,
+                locations=filter_locations,
+                body_parts=filter_body_parts,
+            )
+            logger.info(f"Loaded {len(catalog_features)} filtered catalog features")
+        except ValueError as e:
+            raise ValueError(f"Failed to load filtered catalog features: {e}")
+    else:
+        logger.info(f"Loading catalog features (extractor: {extractor})")
+        try:
+            catalog_features = get_all_catalog_features(
+                catalog_root=catalog_path, extractor=extractor
+            )
+            logger.info(f"Loaded {len(catalog_features)} catalog features")
+        except ValueError as e:
+            raise ValueError(f"Failed to load catalog features: {e}")
+
+    # Initialize LightGlue matcher
+    logger.info(f"Initializing LightGlue matcher with {extractor} features")
+    try:
+        matcher = LightGlue(features=extractor).eval().to(device)
+    except Exception as e:
+        raise ValueError(
+            f"Failed to initialize LightGlue matcher with extractor '{extractor}': {e}"
+        )
+
+    # Move query features to device and add batch dimension
+    query_feats = {}
+    for k, v in query_features.items():
+        if isinstance(v, torch.Tensor):
+            # Add batch dimension if not present
+            if v.ndim == 1:
+                v = v.unsqueeze(0)
+            elif v.ndim == 2:
+                v = v.unsqueeze(0)
+            query_feats[k] = v.to(device)
+        else:
+            query_feats[k] = v
+
+    # Serial matching: iterate through catalog
+    logger.info(f"Matching against {len(catalog_features)} catalog images")
+    matches_dict = {}
+    raw_matches_cache = {}  # Store raw matches for pairwise saving
+
+    for catalog_id, catalog_feats in catalog_features.items():
+        # Move catalog features to device and add batch dimension
+        catalog_feats_device = {}
+        for k, v in catalog_feats.items():
+            if isinstance(v, torch.Tensor):
+                # Add batch dimension if not present
+                if v.ndim == 1:
+                    v = v.unsqueeze(0)
+                elif v.ndim == 2:
+                    v = v.unsqueeze(0)
+                catalog_feats_device[k] = v.to(device)
+            else:
+                catalog_feats_device[k] = v
+
+        # Run matcher
+        try:
+            with torch.no_grad():
+                matches = matcher(
+                    {
+                        "image0": query_feats,
+                        "image1": catalog_feats_device,
+                    }
+                )
+        except Exception as e:
+            logger.warning(f"Matching failed for {catalog_id}: {e}")
+            continue
+
+        # Compute metrics
+        try:
+            metrics = compute_match_metrics(matches)
+            matches_dict[catalog_id] = metrics
+
+            # Cache raw matches and features for top-k pairwise saving
+            if pairwise_output_dir is not None:
+                raw_matches_cache[catalog_id] = {
+                    "matches": matches,
+                    "catalog_features": catalog_feats,
+                }
+        except KeyError as e:
+            logger.warning(f"Failed to compute metrics for {catalog_id}: {e}")
+            continue
+
+    logger.info(f"Successfully matched against {len(matches_dict)} catalog images")
+
+    if not matches_dict:
+        raise RuntimeError(
+            "No successful matches found. All catalog images failed to match. "
+            "This may indicate a problem with feature extraction or format."
+        )
+
+    # Rank matches by Wasserstein distance
+    ranked_matches = rank_matches(matches_dict, metric="wasserstein", top_k=top_k)
+
+    # Enrich matches with catalog metadata
+    enriched_matches = []
+    for match in ranked_matches:
+        catalog_id = match["catalog_id"]
+        metadata = get_catalog_metadata_for_id(
+            catalog_root=catalog_path, catalog_id=catalog_id
+        )
+
+        if metadata is None:
+            logger.warning(f"No metadata found for {catalog_id}")
+            continue
+
+        enriched_match = {
+            "rank": match["rank"],
+            "catalog_id": catalog_id,
+            "leopard_name": metadata["leopard_name"],
+            "filepath": str(metadata["image_path"]),
+            "wasserstein": match["wasserstein"],
+            "auc": match["auc"],
+            "num_matches": match["num_matches"],
+            "individual_id": metadata["individual_id"],
+        }
+        enriched_matches.append(enriched_match)
+
+    if enriched_matches:
+        logger.info(
+            f"Top match: {enriched_matches[0]['leopard_name']} "
+            f"(wasserstein: {enriched_matches[0]['wasserstein']:.4f}, "
+            f"matches: {enriched_matches[0]['num_matches']})"
+        )
+
+    # Save pairwise match data for top-k matches
+    if pairwise_output_dir is not None and enriched_matches:
+        pairwise_output_dir = Path(pairwise_output_dir)
+        pairwise_output_dir.mkdir(parents=True, exist_ok=True)
+
+        logger.info(
+            f"Saving pairwise match data for top-{len(enriched_matches)} matches"
+        )
+
+        # Get query image size
+        query_image_size = query_features.get("image_size")
+        if isinstance(query_image_size, torch.Tensor):
+            query_image_size = query_image_size.cpu().numpy()
+
+        for enriched_match in enriched_matches:
+            catalog_id = enriched_match["catalog_id"]
+
+            # Skip if no cached data for this catalog_id
+            if catalog_id not in raw_matches_cache:
+                logger.warning(
+                    f"No cached match data for {catalog_id}, skipping pairwise save"
+                )
+                enriched_match["pairwise_file"] = None
+                continue
+
+            # Get cached data
+            cached = raw_matches_cache[catalog_id]
+            matches = cached["matches"]
+            catalog_feats = cached["catalog_features"]
+
+            # Extract matched keypoints
+            try:
+                matched_data = extract_matched_keypoints(
+                    query_features=query_features,
+                    catalog_features=catalog_feats,
+                    matches=matches,
+                )
+            except Exception as e:
+                logger.warning(
+                    f"Failed to extract keypoints for {catalog_id}: {e}, skipping"
+                )
+                enriched_match["pairwise_file"] = None
+                continue
+
+            # Get catalog image size
+            catalog_image_size = catalog_feats.get("image_size")
+            if isinstance(catalog_image_size, torch.Tensor):
+                catalog_image_size = catalog_image_size.cpu().numpy()
+
+            # Build pairwise data
+            pairwise_data = {
+                "rank": enriched_match["rank"],
+                "catalog_id": catalog_id,
+                "leopard_name": enriched_match["leopard_name"],
+                "query_image_path": query_image_path or "",
+                "catalog_image_path": enriched_match["filepath"],
+                "query_image_size": query_image_size,
+                "catalog_image_size": catalog_image_size,
+                "query_keypoints": matched_data["query_keypoints"],
+                "catalog_keypoints": matched_data["catalog_keypoints"],
+                "match_scores": matched_data["match_scores"],
+                "wasserstein": enriched_match["wasserstein"],
+                "auc": enriched_match["auc"],
+                "num_matches": matched_data[
+                    "num_matches"
+                ],  # Use actual count from extracted keypoints
+            }
+
+            # Save as compressed NPZ
+            output_filename = f"rank_{enriched_match['rank']:02d}_{catalog_id}.npz"
+            output_path = pairwise_output_dir / output_filename
+
+            np.savez_compressed(output_path, **pairwise_data)
+
+            # Add pairwise file reference to enriched_match (relative to matching stage dir)
+            enriched_match["pairwise_file"] = f"pairwise/{output_filename}"
+
+        logger.info(f"Saved pairwise data to {pairwise_output_dir}")
+    else:
+        # Set pairwise_file to None if not saving pairwise data
+        for enriched_match in enriched_matches:
+            enriched_match["pairwise_file"] = None
+
+    # Return standardized stage dict
+    return {
+        "stage_id": "matching",
+        "stage_name": "Matching",
+        "description": "Match query against catalog using LightGlue",
+        "config": {
+            "top_k": top_k,
+            "extractor": extractor,
+            "device": device,
+            "catalog_path": str(catalog_path),
+            "filter_locations": filter_locations,
+            "filter_body_parts": filter_body_parts,
+        },
+        "metrics": {
+            "num_catalog_images": len(catalog_features),
+            "num_successful_matches": len(matches_dict),
+            "top_match_wasserstein": enriched_matches[0]["wasserstein"]
+            if enriched_matches
+            else 0.0,
+            "top_match_leopard_name": enriched_matches[0]["leopard_name"]
+            if enriched_matches
+            else "",
+        },
+        "data": {
+            "catalog_info": {
+                "catalog_version": catalog_index["catalog_version"],
+                "catalog_path": str(catalog_path),
+                "num_individuals": catalog_index["statistics"]["total_individuals"],
+                "num_reference_images": catalog_index["statistics"][
+                    "total_reference_images"
+                ],
+            },
+            "matches": enriched_matches,
+        },
+    }
+
+
+# ============================================================================
+# Metrics Utilities
+# ============================================================================
+
+
+def compute_wasserstein_distance(scores: np.ndarray) -> float:
+    """Compute Wasserstein distance from null distribution.
+
+    The Wasserstein distance measures how far the match score distribution is from
+    a null distribution (all zeros). Higher values indicate better matches.
+    This is the optimal metric for re-identification tasks.
+
+    Args:
+        scores: Array of match scores (typically from matcher output)
+
+    Returns:
+        Wasserstein distance as a float
+
+    References:
+        Based on trout-reid implementation for animal re-identification
+    """
+    if len(scores) == 0:
+        return 0.0
+
+    # Null distribution: fixed-length array of zeros
+    # This represents no matches at all
+    # Using fixed length (1024) ensures all matches are comparable
+    # to the same reference distribution (follows trout-reID implementation)
+    x_null_distribution = np.zeros(1024)
+
+    # Compute Wasserstein (Earth Mover's) distance
+    distance = wasserstein_distance(x_null_distribution, scores)
+
+    return float(distance)
+
+
+def compute_auc(scores: np.ndarray) -> float:
+    """Compute Area Under Curve (cumulative distribution) of match scores.
+
+    AUC represents the cumulative distribution of match scores.
+    Higher values indicate better matches.
+
+    Args:
+        scores: Array of match scores (typically from matcher output)
+
+    Returns:
+        AUC value as a float (0.0 to 1.0)
+
+    References:
+        Based on trout-reid implementation
+    """
+    if len(scores) == 0:
+        return 0.0
+
+    # Sort scores in ascending order
+    sorted_scores = np.sort(scores)
+
+    # Compute cumulative sum
+    cumsum = np.cumsum(sorted_scores)
+
+    # Normalize by total sum to get AUC in [0, 1]
+    if cumsum[-1] > 0:
+        auc = np.trapz(cumsum / cumsum[-1]) / len(scores)
+    else:
+        auc = 0.0
+
+    return float(auc)
+
+
+def extract_match_scores(matches: dict[str, torch.Tensor]) -> np.ndarray:
+    """Extract match scores from matcher output.
+
+    Args:
+        matches: Dictionary from LightGlue matcher with keys:
+            - matches0: Tensor of matched indices
+            - matching_scores0: Tensor of match confidence scores
+
+    Returns:
+        Numpy array of match scores
+
+    Raises:
+        KeyError: If required keys are missing from matches dict
+    """
+    if "matching_scores0" not in matches:
+        raise KeyError("matches dictionary missing 'matching_scores0' key")
+
+    scores = matches["matching_scores0"]
+
+    # Convert to numpy and filter out invalid matches (-1 values)
+    if isinstance(scores, torch.Tensor):
+        scores = scores.cpu().numpy()
+
+    # Filter out unmatched keypoints (score = 0 or negative)
+    valid_scores = scores[scores > 0]
+
+    return valid_scores
+
+
+def extract_matched_keypoints(
+    query_features: dict[str, torch.Tensor],
+    catalog_features: dict[str, torch.Tensor],
+    matches: dict[str, torch.Tensor],
+) -> dict[str, np.ndarray]:
+    """Extract matched keypoint pairs from matcher output.
+
+    Args:
+        query_features: Query feature dict with 'keypoints' tensor [M, 2]
+        catalog_features: Catalog feature dict with 'keypoints' tensor [N, 2]
+        matches: Dictionary from LightGlue matcher with:
+            - matches0: Tensor [M] mapping query_idx → catalog_idx (-1 if no match)
+            - matching_scores0: Tensor [M] with match confidence scores
+
+    Returns:
+        Dictionary with:
+            - query_keypoints: ndarray [num_matches, 2] - matched query keypoints
+            - catalog_keypoints: ndarray [num_matches, 2] - matched catalog keypoints
+            - match_scores: ndarray [num_matches] - confidence scores
+            - num_matches: int - number of valid matches
+
+    Raises:
+        KeyError: If required keys are missing
+    """
+    if "matches0" not in matches or "matching_scores0" not in matches:
+        raise KeyError(
+            "matches dictionary missing 'matches0' or 'matching_scores0' keys"
+        )
+
+    # Get match indices and scores
+    matches0 = matches["matches0"]  # Shape: [M]
+    scores0 = matches["matching_scores0"]  # Shape: [M]
+
+    # Convert to numpy if tensors
+    if isinstance(matches0, torch.Tensor):
+        matches0 = matches0.cpu().numpy()
+    if isinstance(scores0, torch.Tensor):
+        scores0 = scores0.cpu().numpy()
+
+    # Remove batch dimension if present
+    if matches0.ndim == 2:
+        matches0 = matches0[0]
+    if scores0.ndim == 2:
+        scores0 = scores0[0]
+
+    # Filter valid matches (matched and score > 0)
+    valid_mask = (matches0 >= 0) & (scores0 > 0)
+    valid_indices = matches0[valid_mask].astype(int)
+    valid_scores = scores0[valid_mask]
+
+    # Get keypoints
+    query_kpts = query_features["keypoints"]
+    catalog_kpts = catalog_features["keypoints"]
+
+    # Convert to numpy if tensors
+    if isinstance(query_kpts, torch.Tensor):
+        query_kpts = query_kpts.cpu().numpy()
+    if isinstance(catalog_kpts, torch.Tensor):
+        catalog_kpts = catalog_kpts.cpu().numpy()
+
+    # Remove batch dimension if present
+    if query_kpts.ndim == 3:
+        query_kpts = query_kpts[0]
+    if catalog_kpts.ndim == 3:
+        catalog_kpts = catalog_kpts[0]
+
+    # Extract matched keypoints
+    query_matched = query_kpts[valid_mask]
+    catalog_matched = catalog_kpts[valid_indices]
+
+    return {
+        "query_keypoints": query_matched,
+        "catalog_keypoints": catalog_matched,
+        "match_scores": valid_scores,
+        "num_matches": len(valid_scores),
+    }
+
+
+def rank_matches(
+    matches_dict: dict[str, dict[str, Any]],
+    metric: str = "wasserstein",
+    top_k: int = None,
+) -> list[dict[str, Any]]:
+    """Rank matches by specified metric.
+
+    Args:
+        matches_dict: Dictionary mapping catalog_id to match info
+        metric: Metric to rank by ('wasserstein' or 'auc')
+        top_k: Number of top matches to return (None = all)
+
+    Returns:
+        List of match dictionaries sorted by metric (best first)
+
+    Raises:
+        ValueError: If metric is not supported
+    """
+    if metric not in ["wasserstein", "auc"]:
+        raise ValueError(f"Unsupported metric: {metric}. Use 'wasserstein' or 'auc'")
+
+    # Convert dict to list with catalog_id included
+    matches_list = [
+        {"catalog_id": cid, **match_info} for cid, match_info in matches_dict.items()
+    ]
+
+    # Sort by metric (descending - higher is better for both metrics)
+    sorted_matches = sorted(
+        matches_list,
+        key=lambda x: x.get(metric, 0.0),
+        reverse=True,
+    )
+
+    # Add rank
+    for rank, match in enumerate(sorted_matches, start=1):
+        match["rank"] = rank
+
+    # Return top_k if specified
+    if top_k is not None:
+        return sorted_matches[:top_k]
+
+    return sorted_matches
+
+
+def compute_match_metrics(matches: dict[str, torch.Tensor]) -> dict[str, float]:
+    """Compute all matching metrics for a single match result.
+
+    Args:
+        matches: Dictionary from LightGlue matcher
+
+    Returns:
+        Dictionary with computed metrics:
+            - wasserstein: float
+            - auc: float
+            - num_matches: int
+
+    Raises:
+        KeyError: If matches dict is missing required keys
+    """
+    try:
+        scores = extract_match_scores(matches)
+
+        return {
+            "wasserstein": compute_wasserstein_distance(scores),
+            "auc": compute_auc(scores),
+            "num_matches": len(scores),
+        }
+    except KeyError as e:
+        raise KeyError(f"Failed to compute metrics: {e}")

src/snowleopard_reid/pipeline/stages/preprocess.py

@@ -0,0 +1,142 @@
+"""Preprocessing stage for cropping and masking snow leopard images.
+
+This module provides preprocessing operations to extract and mask the leopard region
+from the full image.
+"""
+
+import logging
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+def run_preprocess_stage(
+    image_path: Path | str,
+    mask: np.ndarray,
+    padding: int = 5,
+) -> dict:
+    """Run preprocessing stage.
+
+    This stage crops the image to the mask bounding box with padding and applies
+    the mask to isolate the leopard region.
+
+    Args:
+        image_path: Path to input image
+        mask: Binary mask (H×W, uint8) from segmentation
+        padding: Padding around bbox in pixels (default: 5)
+
+    Returns:
+        Stage dict with structure:
+        {
+            "stage_id": "preprocessing",
+            "stage_name": "Preprocessing",
+            "description": "Crop and mask leopard region",
+            "config": {
+                "padding": int
+            },
+            "metrics": {
+                "original_size": {"width": int, "height": int},
+                "crop_size": {"width": int, "height": int}
+            },
+            "data": {
+                "cropped_image": PIL.Image,
+                "metadata": {
+                    "original_size": {"width": int, "height": int},
+                    "crop_bbox": {"x_min": int, "y_min": int, "x_max": int, "y_max": int},
+                    "crop_size": {"width": int, "height": int}
+                }
+            }
+        }
+
+    Raises:
+        FileNotFoundError: If image doesn't exist
+        ValueError: If mask is invalid
+    """
+    image_path = Path(image_path)
+
+    if not image_path.exists():
+        raise FileNotFoundError(f"Image not found: {image_path}")
+
+    logger.info(f"Preprocessing image: {image_path}")
+
+    # Load image
+    image = cv2.imread(str(image_path))
+    if image is None:
+        raise RuntimeError(f"Failed to load image: {image_path}")
+    image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+    image_height, image_width = image_rgb.shape[:2]
+
+    # Resize mask to match image dimensions if needed
+    if mask.shape[:2] != (image_height, image_width):
+        mask_resized = cv2.resize(
+            mask.astype(np.uint8),
+            (image_width, image_height),
+            interpolation=cv2.INTER_NEAREST,
+        )
+    else:
+        mask_resized = mask
+
+    # Find bounding box of mask
+    rows = np.any(mask_resized > 0, axis=1)
+    cols = np.any(mask_resized > 0, axis=0)
+
+    if not np.any(rows) or not np.any(cols):
+        raise ValueError("Mask is empty (no pixels > 0)")
+
+    y_min, y_max = np.where(rows)[0][[0, -1]]
+    x_min, x_max = np.where(cols)[0][[0, -1]]
+
+    # Add padding
+    x_min = max(0, x_min - padding)
+    y_min = max(0, y_min - padding)
+    x_max = min(image_width - 1, x_max + padding)
+    y_max = min(image_height - 1, y_max + padding)
+
+    # Crop image and mask
+    cropped_image = image_rgb[y_min : y_max + 1, x_min : x_max + 1]
+    cropped_mask = mask_resized[y_min : y_max + 1, x_min : x_max + 1]
+
+    # Apply mask (set non-masked pixels to black)
+    masked_image = cropped_image.copy()
+    masked_image[cropped_mask == 0] = 0
+
+    # Convert to PIL Image
+    cropped_pil = Image.fromarray(masked_image)
+
+    crop_height, crop_width = masked_image.shape[:2]
+
+    logger.info(
+        f"Cropped from {image_width}x{image_height} to {crop_width}x{crop_height} "
+        f"(padding={padding}px)"
+    )
+
+    # Return standardized stage dict
+    return {
+        "stage_id": "preprocessing",
+        "stage_name": "Preprocessing",
+        "description": "Crop and mask leopard region",
+        "config": {
+            "padding": padding,
+        },
+        "metrics": {
+            "original_size": {"width": image_width, "height": image_height},
+            "crop_size": {"width": crop_width, "height": crop_height},
+        },
+        "data": {
+            "cropped_image": cropped_pil,
+            "metadata": {
+                "original_size": {"width": image_width, "height": image_height},
+                "crop_bbox": {
+                    "x_min": int(x_min),
+                    "y_min": int(y_min),
+                    "x_max": int(x_max),
+                    "y_max": int(y_max),
+                },
+                "crop_size": {"width": crop_width, "height": crop_height},
+            },
+        },
+    }

src/snowleopard_reid/pipeline/stages/segmentation.py

@@ -0,0 +1,453 @@
+"""Segmentation stage using YOLO or GDINO+SAM for snow leopard detection.
+
+This module provides segmentation stages that detect and segment snow leopards
+in query images using either:
+1. YOLO (end-to-end learned segmentation)
+2. GDINO+SAM (zero-shot detection + prompted segmentation)
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+import torch
+from PIL import Image
+from segment_anything_hq import SamPredictor, sam_model_registry
+from transformers import AutoModelForZeroShotObjectDetection, AutoProcessor
+from ultralytics import YOLO
+
+from snowleopard_reid import get_device
+
+logger = logging.getLogger(__name__)
+
+
+def load_gdino_model(
+    model_id: str = "IDEA-Research/grounding-dino-base",
+    device: str | None = None,
+) -> tuple[Any, Any]:
+    """Load Grounding DINO model and processor.
+
+    Args:
+        model_id: HuggingFace model identifier
+        device: Device to load model on (None = auto-detect)
+
+    Returns:
+        Tuple of (processor, model)
+    """
+    device = get_device(device=device, verbose=True)
+
+    logger.info(f"Loading Grounding DINO model: {model_id}")
+    processor = AutoProcessor.from_pretrained(model_id)
+    model = AutoModelForZeroShotObjectDetection.from_pretrained(model_id)
+    model = model.to(device)
+    model.eval()
+
+    logger.info("Grounding DINO model loaded successfully")
+    return processor, model
+
+
+def load_sam_predictor(
+    checkpoint_path: Path | str,
+    model_type: str = "vit_l",
+    device: str | None = None,
+) -> SamPredictor:
+    """Load SAM HQ predictor.
+
+    Args:
+        checkpoint_path: Path to SAM HQ checkpoint file
+        model_type: Model type (vit_b, vit_l, vit_h)
+        device: Device to load model on (None = auto-detect)
+
+    Returns:
+        SamPredictor instance
+    """
+    checkpoint_path = Path(checkpoint_path)
+    if not checkpoint_path.exists():
+        raise FileNotFoundError(f"SAM checkpoint not found: {checkpoint_path}")
+
+    device_str = get_device(device=device, verbose=True)
+
+    logger.info(f"Loading SAM HQ model: {model_type}")
+    sam = sam_model_registry[model_type](checkpoint=str(checkpoint_path))
+    sam.to(device=device_str)
+
+    predictor = SamPredictor(sam)
+    logger.info("SAM HQ model loaded successfully")
+
+    return predictor
+
+
+def _run_yolo_segmentation(
+    model: YOLO,
+    image_path: Path,
+    confidence_threshold: float,
+    device: str,
+) -> dict:
+    """Run YOLO segmentation (internal implementation).
+
+    Args:
+        model: Pre-loaded YOLO model
+        image_path: Path to input image
+        confidence_threshold: Minimum confidence to keep predictions
+        device: Device to run on
+
+    Returns:
+        Standardized stage dict
+    """
+    # Load image to get size
+    image = cv2.imread(str(image_path))
+    if image is None:
+        raise RuntimeError(f"Failed to load image: {image_path}")
+    image_height, image_width = image.shape[:2]
+
+    # Run inference
+    try:
+        results = model(
+            str(image_path),
+            conf=confidence_threshold,
+            device=device,
+            verbose=False,
+        )
+    except Exception as e:
+        raise RuntimeError(f"YOLO inference failed: {e}")
+
+    # Parse results
+    predictions = []
+    result = results[0]  # Single image, so single result
+
+    # Debug: Print result attributes
+    logger.info(f"Result object type: {type(result)}")
+    logger.info(f"Result has boxes: {result.boxes is not None}")
+    logger.info(f"Result has masks: {result.masks is not None}")
+    if result.boxes is not None:
+        logger.info(f"Number of boxes: {len(result.boxes)}")
+    if result.masks is not None:
+        logger.info(f"Number of masks: {len(result.masks)}")
+
+    # Check if any detections found
+    if result.masks is None or len(result.masks) == 0:
+        logger.warning(f"No detections found for {image_path}")
+        logger.warning(
+            f"Boxes present: {result.boxes is not None}, Masks present: {result.masks is not None}"
+        )
+    else:
+        # Extract masks and metadata
+        for idx in range(len(result.masks)):
+            # Get mask (binary, H×W)
+            mask = result.masks.data[idx].cpu().numpy()  # Shape: (H, W)
+            mask = (mask * 255).astype(np.uint8)  # Convert to 0-255
+
+            # Get bounding box (normalized xywh format)
+            bbox = result.boxes.xywhn[idx].cpu().numpy()  # Shape: (4,)
+            x_center, y_center, width, height = bbox
+
+            # Get confidence
+            confidence = float(result.boxes.conf[idx].cpu().numpy())
+
+            # Get class info
+            class_id = int(result.boxes.cls[idx].cpu().numpy())
+            class_name = result.names[class_id]
+
+            predictions.append(
+                {
+                    "mask": mask,
+                    "confidence": confidence,
+                    "bbox_xywhn": {
+                        "x_center": float(x_center),
+                        "y_center": float(y_center),
+                        "width": float(width),
+                        "height": float(height),
+                    },
+                    "class_id": class_id,
+                    "class_name": class_name,
+                }
+            )
+
+        logger.info(
+            f"Found {len(predictions)} predictions (confidence >= {confidence_threshold})"
+        )
+
+    # Return standardized stage dict
+    return {
+        "stage_id": "segmentation",
+        "stage_name": "YOLO Segmentation",
+        "description": "Snow leopard detection and segmentation using YOLO",
+        "config": {
+            "strategy": "yolo",
+            "confidence_threshold": confidence_threshold,
+            "device": device,
+        },
+        "metrics": {
+            "num_predictions": len(predictions),
+        },
+        "data": {
+            "image_path": str(image_path),
+            "image_size": {"width": image_width, "height": image_height},
+            "predictions": predictions,
+        },
+    }
+
+
+def _run_gdino_sam_segmentation(
+    gdino_processor: Any,
+    gdino_model: Any,
+    sam_predictor: SamPredictor,
+    image_path: Path,
+    confidence_threshold: float,
+    text_prompt: str,
+    box_threshold: float,
+    text_threshold: float,
+    device: str,
+) -> dict:
+    """Run GDINO+SAM segmentation (internal implementation).
+
+    Args:
+        gdino_processor: Grounding DINO processor
+        gdino_model: Grounding DINO model
+        sam_predictor: SAM HQ predictor
+        image_path: Path to input image
+        confidence_threshold: Minimum confidence to keep predictions
+        text_prompt: Text prompt for GDINO
+        box_threshold: GDINO box threshold
+        text_threshold: GDINO text threshold
+        device: Device to run on
+
+    Returns:
+        Standardized stage dict
+    """
+    # Load image (PIL for GDINO, numpy for SAM)
+    image_pil = Image.open(image_path).convert("RGB")
+    image_np = np.array(image_pil)
+    image_height, image_width = image_np.shape[:2]
+
+    # Run Grounding DINO detection
+    logger.info("Running Grounding DINO detection...")
+    inputs = gdino_processor(images=image_pil, text=text_prompt, return_tensors="pt")
+    inputs = {k: v.to(device) for k, v in inputs.items()}
+
+    with torch.no_grad():
+        outputs = gdino_model(**inputs)
+
+    # Post-process GDINO outputs
+    results = gdino_processor.post_process_grounded_object_detection(
+        outputs,
+        inputs["input_ids"],
+        threshold=box_threshold,
+        text_threshold=text_threshold,
+        target_sizes=[image_pil.size[::-1]],  # (height, width)
+    )[0]
+
+    # Filter by confidence threshold
+    labels = results.get("text_labels", results.get("labels", []))
+    boxes = results["boxes"]
+    scores = results["scores"]
+
+    logger.info(f"GDINO detected {len(boxes)} objects")
+
+    # Filter predictions by confidence threshold
+    filtered_detections = [
+        (box, score, label)
+        for box, score, label in zip(boxes, scores, labels)
+        if float(score) >= confidence_threshold
+    ]
+
+    logger.info(
+        f"Filtered to {len(filtered_detections)} detections (confidence >= {confidence_threshold})"
+    )
+
+    if not filtered_detections:
+        logger.warning(f"No detections found for {image_path}")
+        predictions = []
+    else:
+        # Set image for SAM (do this once)
+        logger.info("Running SAM HQ segmentation...")
+        sam_predictor.set_image(image_np)
+
+        predictions = []
+        for idx, (box, gdino_score, label) in enumerate(filtered_detections):
+            # Convert box to pixel coordinates and format for SAM
+            x_min, y_min, x_max, y_max = box
+            bbox_xyxy = np.array(
+                [float(x_min), float(y_min), float(x_max), float(y_max)]
+            )
+
+            # Run SAM with bounding box prompt
+            masks, sam_scores, logits = sam_predictor.predict(
+                box=bbox_xyxy[None, :],
+                multimask_output=False,
+                hq_token_only=True,
+            )
+
+            # Get mask (first and only mask, since multimask_output=False)
+            mask = masks[0]  # Shape: (H, W), boolean
+            sam_score = float(sam_scores[0])
+
+            # Convert mask to uint8 (0-255)
+            mask_uint8 = (mask * 255).astype(np.uint8)
+
+            # Convert bbox to normalized xywh format (same as YOLO)
+            x_center = (float(x_min) + float(x_max)) / 2 / image_width
+            y_center = (float(y_min) + float(y_max)) / 2 / image_height
+            width = (float(x_max) - float(x_min)) / image_width
+            height = (float(y_max) - float(y_min)) / image_height
+
+            predictions.append(
+                {
+                    "mask": mask_uint8,
+                    "confidence": float(
+                        gdino_score
+                    ),  # Use GDINO score as primary confidence
+                    "bbox_xywhn": {
+                        "x_center": x_center,
+                        "y_center": y_center,
+                        "width": width,
+                        "height": height,
+                    },
+                    "class_id": 0,  # Single class (snow leopard)
+                    "class_name": label,
+                    # Additional metadata
+                    "sam_score": sam_score,
+                    "gdino_score": float(gdino_score),
+                }
+            )
+
+        logger.info(f"Generated {len(predictions)} segmentation masks")
+
+    # Return standardized stage dict
+    return {
+        "stage_id": "segmentation",
+        "stage_name": "GDINO+SAM Segmentation",
+        "description": "Snow leopard detection using Grounding DINO and segmentation using SAM HQ",
+        "config": {
+            "strategy": "gdino_sam",
+            "confidence_threshold": confidence_threshold,
+            "text_prompt": text_prompt,
+            "box_threshold": box_threshold,
+            "text_threshold": text_threshold,
+            "device": device,
+        },
+        "metrics": {
+            "num_predictions": len(predictions),
+        },
+        "data": {
+            "image_path": str(image_path),
+            "image_size": {"width": image_width, "height": image_height},
+            "predictions": predictions,
+        },
+    }
+
+
+def run_segmentation_stage(
+    image_path: Path | str,
+    strategy: str = "yolo",
+    confidence_threshold: float = 0.5,
+    device: str | None = None,
+    # YOLO-specific parameters
+    yolo_model: YOLO | None = None,
+    # GDINO+SAM-specific parameters
+    gdino_processor: Any | None = None,
+    gdino_model: Any | None = None,
+    sam_predictor: SamPredictor | None = None,
+    text_prompt: str = "a snow leopard.",
+    box_threshold: float = 0.30,
+    text_threshold: float = 0.20,
+) -> dict:
+    """Run segmentation on query image using specified strategy.
+
+    This stage performs snow leopard detection and segmentation using either:
+    - YOLO: End-to-end learned segmentation
+    - GDINO+SAM: Zero-shot detection + prompted segmentation
+
+    Args:
+        image_path: Path to input image
+        strategy: Segmentation strategy ("yolo" or "gdino_sam")
+        confidence_threshold: Minimum confidence to keep predictions (default: 0.5)
+        device: Device to run on ('cpu', 'cuda', or None for auto-detect)
+        yolo_model: Pre-loaded YOLO model (required if strategy="yolo")
+        gdino_processor: Pre-loaded GDINO processor (required if strategy="gdino_sam")
+        gdino_model: Pre-loaded GDINO model (required if strategy="gdino_sam")
+        sam_predictor: Pre-loaded SAM predictor (required if strategy="gdino_sam")
+        text_prompt: Text prompt for GDINO (default: "a snow leopard.")
+        box_threshold: GDINO box confidence threshold (default: 0.30)
+        text_threshold: GDINO text matching threshold (default: 0.20)
+
+    Returns:
+        Stage dict with structure:
+        {
+            "stage_id": "segmentation",
+            "stage_name": str,
+            "description": str,
+            "config": {
+                "strategy": str,
+                "confidence_threshold": float,
+                "device": str,
+                ...
+            },
+            "metrics": {
+                "num_predictions": int
+            },
+            "data": {
+                "image_path": str,
+                "image_size": {"width": int, "height": int},
+                "predictions": [
+                    {
+                        "mask": np.ndarray (H×W, uint8),
+                        "confidence": float,
+                        "bbox_xywhn": {...},
+                        "class_id": int,
+                        "class_name": str,
+                        # Optional (GDINO+SAM only)
+                        "sam_score": float,
+                        "gdino_score": float,
+                    },
+                    ...
+                ]
+            }
+        }
+
+    Raises:
+        ValueError: If strategy is invalid or required models are missing
+        FileNotFoundError: If image doesn't exist
+        RuntimeError: If inference fails
+    """
+    image_path = Path(image_path)
+
+    # Validate inputs
+    if not image_path.exists():
+        raise FileNotFoundError(f"Image not found: {image_path}")
+
+    if strategy not in ["yolo", "gdino_sam"]:
+        raise ValueError(f"Invalid strategy: {strategy}. Must be 'yolo' or 'gdino_sam'")
+
+    # Auto-detect device if not specified
+    device = get_device(device=device, verbose=True)
+
+    # Dispatch to appropriate implementation
+    if strategy == "yolo":
+        if yolo_model is None:
+            raise ValueError("yolo_model is required when strategy='yolo'")
+        return _run_yolo_segmentation(
+            model=yolo_model,
+            image_path=image_path,
+            confidence_threshold=confidence_threshold,
+            device=device,
+        )
+
+    elif strategy == "gdino_sam":
+        if gdino_processor is None or gdino_model is None or sam_predictor is None:
+            raise ValueError(
+                "gdino_processor, gdino_model, and sam_predictor are required when strategy='gdino_sam'"
+            )
+        return _run_gdino_sam_segmentation(
+            gdino_processor=gdino_processor,
+            gdino_model=gdino_model,
+            sam_predictor=sam_predictor,
+            image_path=image_path,
+            confidence_threshold=confidence_threshold,
+            text_prompt=text_prompt,
+            box_threshold=box_threshold,
+            text_threshold=text_threshold,
+            device=device,
+        )

src/snowleopard_reid/utils.py

@@ -0,0 +1,59 @@
+"""Utility functions for snow leopard re-identification.
+
+This module provides common utilities used across the project.
+"""
+
+import logging
+
+import torch
+
+logger = logging.getLogger(__name__)
+
+
+def get_device(device: str | None = None, verbose: bool = True) -> str:
+    """Get the device to use for computation.
+
+    Auto-detects GPU if available, or uses CPU as fallback.
+    Optionally allows manual override.
+
+    Args:
+        device: Manual device override ('cpu', 'cuda', or None for auto-detect)
+        verbose: Whether to log device information
+
+    Returns:
+        Device string ('cuda' or 'cpu')
+
+    Examples:
+        >>> device = get_device()  # Auto-detect
+        >>> device = get_device('cpu')  # Force CPU
+        >>> device = get_device('cuda')  # Force CUDA (will fail if not available)
+    """
+    if device is None:
+        # Auto-detect
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+
+        if verbose:
+            if device == "cuda":
+                gpu_name = torch.cuda.get_device_name(0)
+                gpu_memory = torch.cuda.get_device_properties(0).total_memory / (
+                    1024**3
+                )
+                logger.info(f"Using GPU: {gpu_name} ({gpu_memory:.1f} GB)")
+            else:
+                logger.info("Using CPU (no GPU available)")
+    else:
+        # Manual override
+        device = device.lower()
+        if device not in ["cpu", "cuda"]:
+            raise ValueError(f"Invalid device: {device}. Must be 'cpu' or 'cuda'")
+
+        if device == "cuda" and not torch.cuda.is_available():
+            raise RuntimeError(
+                "CUDA device requested but CUDA is not available. "
+                "Install CUDA-enabled PyTorch or use device='cpu'"
+            )
+
+        if verbose:
+            logger.info(f"Using device: {device}")
+
+    return device

src/snowleopard_reid/visualization.py

@@ -0,0 +1,215 @@
+"""Visualization utilities for snow leopard re-identification.
+
+This module provides functions for visualizing keypoints, matches, and other
+pipeline outputs for debugging and presentation.
+"""
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+def draw_keypoints_overlay(
+    image_path: Path | str,
+    keypoints: np.ndarray,
+    max_keypoints: int = 500,
+    color: str = "blue",
+    ps: int = 10,
+) -> Image.Image:
+    """Draw keypoints overlaid on an image.
+
+    Args:
+        image_path: Path to image file
+        keypoints: Keypoints array of shape [N, 2] with (x, y) coordinates
+        max_keypoints: Maximum number of keypoints to display
+        color: Color name ('blue', 'red', 'green', etc.)
+        ps: Point size for keypoints
+
+    Returns:
+        PIL Image with keypoints drawn
+    """
+    # Load image
+    img = cv2.imread(str(image_path))
+    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+
+    # Color mapping
+    color_map = {
+        "blue": (0, 0, 255),
+        "red": (255, 0, 0),
+        "green": (0, 255, 0),
+        "yellow": (255, 255, 0),
+        "cyan": (0, 255, 255),
+        "magenta": (255, 0, 255),
+    }
+    color_rgb = color_map.get(color.lower(), (0, 0, 255))
+
+    # Draw keypoints (limit to max_keypoints)
+    n_keypoints = min(len(keypoints), max_keypoints)
+    for i in range(n_keypoints):
+        x, y = keypoints[i]
+        cv2.circle(img_rgb, (int(x), int(y)), ps // 2, color_rgb, -1)
+
+    return Image.fromarray(img_rgb)
+
+
+def draw_matched_keypoints(
+    query_image_path: Path | str,
+    catalog_image_path: Path | str,
+    query_keypoints: np.ndarray,
+    catalog_keypoints: np.ndarray,
+    match_scores: np.ndarray,
+    max_matches: int = 100,
+) -> Image.Image:
+    """Draw matched keypoints side-by-side with connecting lines.
+
+    Args:
+        query_image_path: Path to query image
+        catalog_image_path: Path to catalog image
+        query_keypoints: Query keypoints [N, 2]
+        catalog_keypoints: Catalog keypoints [N, 2]
+        match_scores: Match confidence scores [N]
+        max_matches: Maximum number of matches to display
+
+    Returns:
+        PIL Image with side-by-side images and match lines
+    """
+    # Load images
+    query_img = cv2.imread(str(query_image_path))
+    catalog_img = cv2.imread(str(catalog_image_path))
+
+    # Convert to RGB
+    query_rgb = cv2.cvtColor(query_img, cv2.COLOR_BGR2RGB)
+    catalog_rgb = cv2.cvtColor(catalog_img, cv2.COLOR_BGR2RGB)
+
+    # Resize images to same height for side-by-side display
+    max_height = 800
+    query_h, query_w = query_rgb.shape[:2]
+    catalog_h, catalog_w = catalog_rgb.shape[:2]
+
+    # Calculate scaling factors
+    if query_h > max_height or catalog_h > max_height:
+        query_scale = max_height / query_h
+        catalog_scale = max_height / catalog_h
+    else:
+        query_scale = 1.0
+        catalog_scale = 1.0
+
+    # Resize images
+    new_query_h = int(query_h * query_scale)
+    new_query_w = int(query_w * query_scale)
+    new_catalog_h = int(catalog_h * catalog_scale)
+    new_catalog_w = int(catalog_w * catalog_scale)
+
+    query_resized = cv2.resize(query_rgb, (new_query_w, new_query_h))
+    catalog_resized = cv2.resize(catalog_rgb, (new_catalog_w, new_catalog_h))
+
+    # Scale keypoints
+    query_kpts_scaled = query_keypoints * query_scale
+    catalog_kpts_scaled = catalog_keypoints * catalog_scale
+
+    # Create side-by-side canvas
+    combined_h = max(new_query_h, new_catalog_h)
+    combined_w = new_query_w + new_catalog_w
+    canvas = np.zeros((combined_h, combined_w, 3), dtype=np.uint8)
+
+    # Place images on canvas
+    canvas[:new_query_h, :new_query_w] = query_resized
+    canvas[:new_catalog_h, new_query_w : new_query_w + new_catalog_w] = catalog_resized
+
+    # Offset catalog keypoints to account for horizontal placement
+    catalog_kpts_offset = catalog_kpts_scaled.copy()
+    catalog_kpts_offset[:, 0] += new_query_w
+
+    # Draw matches (limit to max_matches)
+    n_matches = min(len(query_kpts_scaled), max_matches)
+
+    # Sort by match scores (highest confidence first)
+    if len(match_scores) > 0:
+        sorted_indices = np.argsort(match_scores)[::-1][:n_matches]
+    else:
+        sorted_indices = np.arange(n_matches)
+
+    # Draw lines and keypoints
+    for idx in sorted_indices:
+        query_pt = tuple(query_kpts_scaled[idx].astype(int))
+        catalog_pt = tuple(catalog_kpts_offset[idx].astype(int))
+
+        # Color based on match score (green = high, yellow = medium, red = low)
+        score = match_scores[idx] if len(match_scores) > 0 else 0.5
+        if score > 0.8:
+            color = (0, 255, 0)  # Green
+        elif score > 0.5:
+            color = (255, 255, 0)  # Yellow
+        else:
+            color = (255, 0, 0)  # Red
+
+        # Draw line
+        cv2.line(canvas, query_pt, catalog_pt, color, 1)
+
+        # Draw keypoints
+        cv2.circle(canvas, query_pt, 5, (255, 0, 0), -1)
+        cv2.circle(canvas, catalog_pt, 5, (0, 0, 255), -1)
+
+    return Image.fromarray(canvas)
+
+
+def draw_side_by_side_comparison(
+    query_image_path: Path | str,
+    catalog_image_path: Path | str,
+    max_height: int = 800,
+) -> Image.Image:
+    """Draw query and catalog images side-by-side without keypoints or annotations.
+
+    This provides a clean visual comparison of the two images without the visual
+    clutter of feature matching overlays. Useful for assessing overall visual
+    similarity and spotting patterns like spots, scars, or markings.
+
+    Args:
+        query_image_path: Path to query image
+        catalog_image_path: Path to catalog/reference image
+        max_height: Maximum height for resizing (default: 800)
+
+    Returns:
+        PIL Image with side-by-side images (no annotations)
+    """
+    # Load images
+    query_img = cv2.imread(str(query_image_path))
+    catalog_img = cv2.imread(str(catalog_image_path))
+
+    # Convert to RGB
+    query_rgb = cv2.cvtColor(query_img, cv2.COLOR_BGR2RGB)
+    catalog_rgb = cv2.cvtColor(catalog_img, cv2.COLOR_BGR2RGB)
+
+    # Resize images to same height for side-by-side display
+    query_h, query_w = query_rgb.shape[:2]
+    catalog_h, catalog_w = catalog_rgb.shape[:2]
+
+    # Calculate scaling factors
+    if query_h > max_height or catalog_h > max_height:
+        query_scale = max_height / query_h
+        catalog_scale = max_height / catalog_h
+    else:
+        query_scale = 1.0
+        catalog_scale = 1.0
+
+    # Resize images
+    new_query_h = int(query_h * query_scale)
+    new_query_w = int(query_w * query_scale)
+    new_catalog_h = int(catalog_h * catalog_scale)
+    new_catalog_w = int(catalog_w * catalog_scale)
+
+    query_resized = cv2.resize(query_rgb, (new_query_w, new_query_h))
+    catalog_resized = cv2.resize(catalog_rgb, (new_catalog_w, new_catalog_h))
+
+    # Create side-by-side canvas
+    combined_h = max(new_query_h, new_catalog_h)
+    combined_w = new_query_w + new_catalog_w
+    canvas = np.zeros((combined_h, combined_w, 3), dtype=np.uint8)
+
+    # Place images on canvas (no keypoints or lines)
+    canvas[:new_query_h, :new_query_w] = query_resized
+    canvas[:new_catalog_h, new_query_w : new_query_w + new_catalog_w] = catalog_resized
+
+    return Image.fromarray(canvas)