Initial commit

DINOv3CosSimilarity.py

@@ -0,0 +1,434 @@
+# filepath: DINOv3-PatchSimilarity/DINOv3CosSimilarity2Images.py
+# filepath: DINOv3-PatchSimilarity/DINOv3CosSimilarity.py
+# Interactive DINOv3 patch similarity viewer for one or two images
+# Interactive DINOv3 patch similarity viewer (NO AutoImageProcessor, NO resize)
+# - Single-image mode (0 or 1 image given): original behavior
+# - Two-image mode (2 images given): when you click or move on one image,
+#   shows BOTH overlays (self on source, cross on target).
+#   NEW: Red selection rectangle is hidden on the non-active image.
+
+import sys, math, io, urllib.request, argparse, os
+import numpy as np
+from PIL import Image
+import torch
+from torchvision import transforms
+import matplotlib
+try:
+    matplotlib.use("TkAgg")
+except Exception:
+    pass
+import matplotlib.pyplot as plt
+from matplotlib.patches import Rectangle
+from transformers import AutoModel
+
+# ---------- Defaults / knobs ----------
+DEFAULT_URL = "http://images.cocodataset.org/val2017/000000039769.jpg"
+DEFAULT_MODEL_ID = "facebook/dinov3-vits16-pretrain-lvd1689m"
+
+SHOW_GRID = True
+ANNOTATE_INDICES = False
+OVERLAY_ALPHA = 0.55
+PATCH_SIZE_OVERRIDE = None   # set 16 to force; None = read from model if available
+
+# ---------- Image I/O ----------
+def load_image(path_or_url):
+    if str(path_or_url).startswith(("http://", "https://")):
+        with urllib.request.urlopen(path_or_url) as resp:
+            data = resp.read()
+        return Image.open(io.BytesIO(data)).convert("RGB")
+    return Image.open(path_or_url).convert("RGB")
+
+# ---------- Preprocessing (custom, no resize) ----------
+def pad_to_multiple(pil_img, multiple=16):
+    W, H = pil_img.size
+    H_pad = int(math.ceil(H / multiple) * multiple)
+    W_pad = int(math.ceil(W / multiple) * multiple)
+    if (H_pad, W_pad) == (H, W):
+        return pil_img, (0, 0, 0, 0)
+    canvas = Image.new("RGB", (W_pad, H_pad), (0, 0, 0))
+    canvas.paste(pil_img, (0, 0))
+    return canvas, (0, 0, W_pad - W, H_pad - H)
+
+def preprocess_image_no_resize(pil_img, multiple=16):
+    img_padded, pad_box = pad_to_multiple(pil_img, multiple=multiple)
+    transform = transforms.Compose([
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std=[0.229, 0.224, 0.225])
+    ])
+    pixel_tensor = transform(img_padded).unsqueeze(0)  # (1,3,H,W)
+    disp_np = np.array(img_padded, dtype=np.uint8)     # (H,W,3) for display
+    return {"pixel_values": pixel_tensor}, disp_np, pad_box
+
+# ---------- Utilities ----------
+def upsample_nearest(arr, H, W, ps):
+    if arr.ndim == 2:
+        return arr.repeat(ps, 0).repeat(ps, 1)
+    elif arr.ndim == 3:
+        # arr shape: (rows, cols, channels)
+        rows, cols, channels = arr.shape
+        arr_up = arr.repeat(ps, 0).repeat(ps, 1)
+        return arr_up.reshape(rows * ps, cols * ps, channels)
+    raise ValueError("upsample_nearest expects (rows,cols) or (rows,cols,channels)")
+
+def draw_grid(ax, rows, cols, ps):
+    for r in range(1, rows):
+        ax.axhline(r * ps - 0.5, lw=0.8, alpha=0.6, color="white", zorder=3)
+    for c in range(1, cols):
+        ax.axvline(c * ps - 0.5, lw=0.8, alpha=0.6, color="white", zorder=3)
+
+def draw_indices(ax, rows, cols, ps):
+    for r in range(rows):
+        for c in range(cols):
+            idx = r * cols + c
+            ax.text(c * ps + ps / 2, r * ps + ps / 2, str(idx),
+                    ha="center", va="center", fontsize=7,
+                    color="white", alpha=0.95, zorder=4)
+
+def rc_to_idx(r, c, cols): return int(r) * cols + int(c)
+def idx_to_rc(i, cols):    return (int(i) // cols, int(i) % cols)
+
+# ---------- Per-image embeddings ----------
+class PatchImageState:
+    def __init__(self, pil_img, model, device, ps):
+        self.pil = pil_img
+        self.ps = ps
+        inputs, disp_np, _ = preprocess_image_no_resize(pil_img, multiple=ps)
+        self.disp = disp_np
+        self.pixel_values = inputs["pixel_values"].to(device)  # (1,3,H,W)
+        _, _, self.H, self.W = self.pixel_values.shape
+        self.rows, self.cols = self.H // ps, self.W // ps
+
+        with torch.no_grad():
+            out = model(pixel_values=self.pixel_values)
+        hs = out.last_hidden_state.squeeze(0).detach().cpu().numpy()  # (T,D)
+
+        T, D = hs.shape
+        n_patches = self.rows * self.cols
+        n_special = T - n_patches  # class + possible register tokens
+        if n_special < 1:
+            raise RuntimeError(
+                f"[error] Token shape mismatch. T={T}, rows*cols={n_patches}, HxW={self.H}x{self.W}, ps={ps}"
+            )
+
+        self.D = D
+        self.patch_embs = hs[n_special:, :].reshape(self.rows, self.cols, D)  # (rows,cols,D)
+        self.X = self.patch_embs.reshape(-1, D)  # (N,D)
+        self.Xn = self.X / (np.linalg.norm(self.X, axis=1, keepdims=True) + 1e-8)  # normalized
+
+        # UI bits (set later by the viewers)
+        self.ax = None
+        self.overlay_im = None
+        self.sel_rect = None
+        self.best_rect = None
+
+# ---------- Single-image mode ----------
+def run_single_image(img_path, model, device, ps, show_grid, annotate_indices, overlay_alpha):
+    img = load_image(img_path)
+    st = PatchImageState(img, model, device, ps)
+
+    fig, ax = plt.subplots(figsize=(9, 9))
+    st.ax = ax
+    ax.imshow(st.disp, zorder=0)
+    ax.set_axis_off()
+    if show_grid:
+        draw_grid(ax, st.rows, st.cols, st.ps)
+    if annotate_indices:
+        draw_indices(ax, st.rows, st.cols, st.ps)
+
+    # neutral overlay to start
+    init_scalar = 0.5 * np.ones((st.rows, st.cols), dtype=np.float32)
+    rgba = plt.get_cmap("magma")(init_scalar)
+    rgba_up = upsample_nearest(rgba, st.H, st.W, st.ps)
+    st.overlay_im = ax.imshow(rgba_up, alpha=overlay_alpha, zorder=1)
+
+    st.sel_rect = Rectangle((0, 0), st.ps, st.ps, fill=False, lw=2.0, ec="red", zorder=5)
+    ax.add_patch(st.sel_rect)
+
+    current_idx = (st.rows // 2) * st.cols + st.cols // 2
+    cmap = plt.get_cmap("magma")
+
+    def update(idx):
+        nonlocal current_idx
+        current_idx = int(np.clip(idx, 0, st.rows * st.cols - 1))
+        r, c = idx_to_rc(current_idx, st.cols)
+
+        q = st.X[current_idx]
+        qn = q / (np.linalg.norm(q) + 1e-8)
+        cos = st.Xn @ qn
+        cos_map = cos.reshape(st.rows, st.cols)
+
+        disp = (cos_map - cos_map.min()) / (cos_map.ptp() + 1e-8)
+        rgba = cmap(disp)
+        # Force selected cell to pure RED (and full alpha in the RGBA array)
+        rgba[r, c, 0:3] = np.array([1.0, 0.0, 0.0])
+        rgba[r, c, 3]   = 1.0
+
+        st.overlay_im.set_data(upsample_nearest(rgba, st.H, st.W, st.ps))
+        st.overlay_im.set_alpha(overlay_alpha)  # global alpha
+
+        st.sel_rect.set_xy((c * st.ps, r * st.ps))
+        ax.set_title(
+            f"Single-image • idx={current_idx} (r={r}, c={c}) • cos∈[{cos_map.min():.3f},{cos_map.max():.3f}]",
+            fontsize=11
+        )
+        fig.canvas.draw_idle()
+
+    def on_click(event):
+        if event.inaxes != ax or event.xdata is None or event.ydata is None:
+            return
+        r = int(np.clip(event.ydata // st.ps, 0, st.rows - 1))
+        c = int(np.clip(event.xdata // st.ps, 0, st.cols - 1))
+        update(rc_to_idx(r, c, st.cols))
+
+    def on_key(event):
+        nonlocal current_idx
+        r, c = idx_to_rc(current_idx, st.cols)
+        if event.key == "left":
+            c = max(0, c - 1)
+        elif event.key == "right":
+            c = min(st.cols - 1, c + 1)
+        elif event.key == "up":
+            r = max(0, r - 1)
+        elif event.key == "down":
+            r = min(st.rows - 1, r + 1)
+        elif event.key == "q":
+            plt.close(fig); return
+        else:
+            return
+        update(rc_to_idx(r, c, st.cols))
+
+    fig.canvas.mpl_connect("button_press_event", on_click)
+    fig.canvas.mpl_connect("key_press_event", on_key)
+
+    update(current_idx)
+    print("[single-image] Controls: click to select • arrows to move • 'q' to quit")
+    plt.tight_layout()
+    plt.show()
+
+# ---------- Two-image mode (shows BOTH overlays; hides red rect on non-active) ----------
+def run_two_images(img1_path, img2_path, model, device, ps, show_grid, annotate_indices, overlay_alpha):
+    img1, img2 = load_image(img1_path), load_image(img2_path)
+    S = [PatchImageState(img1, model, device, ps),
+         PatchImageState(img2, model, device, ps)]
+    if S[0].D != S[1].D:
+        raise RuntimeError("Embedding dims differ — use the same model for both images.")
+
+    fig, (axL, axR) = plt.subplots(1, 2, figsize=(12, 6))
+    axs = [axL, axR]
+    for i, (ax, st) in enumerate(zip(axs, S)):
+        st.ax = ax
+        ax.imshow(st.disp, zorder=0)
+        ax.set_axis_off()
+        if show_grid:
+            draw_grid(ax, st.rows, st.cols, st.ps)
+        if annotate_indices:
+            draw_indices(ax, st.rows, st.cols, st.ps)
+        # start overlays (hidden until first render)
+        init_scalar = 0.5 * np.ones((st.rows, st.cols), dtype=np.float32)
+        rgba = plt.get_cmap("magma")(init_scalar)
+        rgba_up = upsample_nearest(rgba, st.H, st.W, st.ps)
+        st.overlay_im = ax.imshow(rgba_up, alpha=0.0, zorder=1)
+
+        st.sel_rect  = Rectangle((0, 0), st.ps, st.ps, fill=False, lw=2.0, ec="red",    zorder=5)
+        st.best_rect = Rectangle((0, 0), st.ps, st.ps, fill=False, lw=2.0, ec="yellow", zorder=6)
+        ax.add_patch(st.sel_rect)
+        ax.add_patch(st.best_rect)
+        st.best_rect.set_visible(False)
+
+    active_side = 0  # 0=left, 1=right
+    current_idx = [ (S[0].rows//2)*S[0].cols + S[0].cols//2,
+                    (S[1].rows//2)*S[1].cols + S[1].cols//2 ]
+    cmap = plt.get_cmap("magma")
+
+    def set_titles(src_i=None, self_stats=None, cross_stats=None):
+        axs[0].set_title(f"LEFT  • {S[0].rows}x{S[0].cols} patches • {'ACTIVE' if active_side==0 else ''}", fontsize=10)
+        axs[1].set_title(f"RIGHT • {S[1].rows}x{S[1].cols} patches • {'ACTIVE' if active_side==1 else ''}", fontsize=10)
+        if src_i is not None and self_stats is not None and cross_stats is not None:
+            src_name = "LEFT" if src_i == 0 else "RIGHT"
+            tgt_name = "RIGHT" if src_i == 0 else "LEFT"
+            fig.suptitle(
+                f"Source: {src_name}  |  Self cos∈[{self_stats[0]:.3f},{self_stats[1]:.3f}]  •  "
+                f"{tgt_name} cos∈[{cross_stats[0]:.3f},{cross_stats[1]:.3f}]  |  "
+                f"Controls: click=select • arrows=move • '1'/'2'/'t'=switch side • 'q'=quit",
+                fontsize=11
+            )
+        else:
+            fig.suptitle(
+                "Controls: click=select • arrows=move • '1'/'2'/'t'=switch side • 'q'=quit",
+                fontsize=11
+            )
+
+    def clamp_idx(i, st):
+        return int(np.clip(i, 0, st.rows*st.cols - 1))
+
+    def update_selection_rects():
+        # position rects
+        for i, st in enumerate(S):
+            r, c = idx_to_rc(current_idx[i], st.cols)
+            st.sel_rect.set_xy((c * st.ps, r * st.ps))
+        # visibility: only active side shows red rect
+        for i, st in enumerate(S):
+            st.sel_rect.set_visible(i == active_side)
+
+    def compute_and_show_both_from_src(src_i):
+        """Show self-similarity on src and cross-similarity on the other image."""
+        src = S[src_i]
+        tgt_i = 1 - src_i
+        tgt = S[tgt_i]
+
+        q_idx = clamp_idx(current_idx[src_i], src)
+        q = src.X[q_idx]
+        qn = q / (np.linalg.norm(q) + 1e-8)
+
+        # --- Self on src ---
+        cos_self = src.Xn @ qn
+        cos_map_self = cos_self.reshape(src.rows, src.cols)
+        disp_self = (cos_map_self - cos_map_self.min()) / (cos_map_self.ptp() + 1e-8)
+        rgba_self = cmap(disp_self)
+        r0, c0 = idx_to_rc(q_idx, src.cols)
+        rgba_self[r0, c0, 0:3] = np.array([1.0, 0.0, 0.0])
+        rgba_self[r0, c0, 3]   = 1.0
+        src.overlay_im.set_data(upsample_nearest(rgba_self, src.H, src.W, src.ps))
+        src.overlay_im.set_alpha(overlay_alpha)
+
+        # --- Cross on tgt ---
+        cos_cross = tgt.Xn @ qn
+        cos_map_cross = cos_cross.reshape(tgt.rows, tgt.cols)
+        disp_cross = (cos_map_cross - cos_map_cross.min()) / (cos_map_cross.ptp() + 1e-8)
+        rgba_cross = cmap(disp_cross)
+        tgt.overlay_im.set_data(upsample_nearest(rgba_cross, tgt.H, tgt.W, tgt.ps))
+        tgt.overlay_im.set_alpha(overlay_alpha)
+
+        # highlight best match on target
+        best = int(np.argmax(cos_cross))
+        br, bc = idx_to_rc(best, tgt.cols)
+        tgt.best_rect.set_xy((bc * tgt.ps, br * tgt.ps))
+        tgt.best_rect.set_visible(True)
+
+        # Hide best on source (self best is the selected cell)
+        src.best_rect.set_visible(False)
+
+        set_titles(src_i, (cos_map_self.min(), cos_map_self.max()),
+                          (cos_map_cross.min(), cos_map_cross.max()))
+        fig.canvas.draw_idle()
+
+    def on_click(event):
+        nonlocal active_side
+        if event.inaxes is None or event.xdata is None or event.ydata is None:
+            return
+        side = 0 if event.inaxes is axs[0] else (1 if event.inaxes is axs[1] else None)
+        if side is None: return
+        st = S[side]
+        r = int(np.clip(event.ydata // st.ps, 0, st.rows - 1))
+        c = int(np.clip(event.xdata // st.ps, 0, st.cols - 1))
+        current_idx[side] = rc_to_idx(r, c, st.cols)
+        active_side = side
+        update_selection_rects()        # <-- updates visibility
+        compute_and_show_both_from_src(active_side)
+
+    def on_key(event):
+        nonlocal active_side
+        if event.key == "q":
+            plt.close(fig); return
+        if event.key in ("t", "T"):
+            active_side = 1 - active_side
+            update_selection_rects()    # <-- updates visibility
+            compute_and_show_both_from_src(active_side); return
+        if event.key == "1":
+            active_side = 0
+            update_selection_rects()
+            compute_and_show_both_from_src(active_side); return
+        if event.key == "2":
+            active_side = 1
+            update_selection_rects()
+            compute_and_show_both_from_src(active_side); return
+
+        st = S[active_side]
+        r, c = idx_to_rc(current_idx[active_side], st.cols)
+        if event.key == "left":
+            c = max(0, c - 1)
+        elif event.key == "right":
+            c = min(st.cols - 1, c + 1)
+        elif event.key == "up":
+            r = max(0, r - 1)
+        elif event.key == "down":
+            r = min(st.rows - 1, r + 1)
+        else:
+            return
+        current_idx[active_side] = rc_to_idx(r, c, st.cols)
+        update_selection_rects()        # keep visibility rule consistent
+        compute_and_show_both_from_src(active_side)
+
+    update_selection_rects()            # initialize positions + visibility
+    set_titles()
+    compute_and_show_both_from_src(active_side)
+
+    fig.canvas.mpl_connect("button_press_event", on_click)
+    fig.canvas.mpl_connect("key_press_event", on_key)
+
+    print("[two-image BOTH] Controls:")
+    print("  • Click on LEFT/RIGHT to select query patch (shows self + cross overlays)")
+    print("  • Arrow keys move selection on ACTIVE side")
+    print("  • '1'/'2'/'t' to switch side • 'q' to quit")
+    plt.tight_layout()
+    plt.show()
+
+# ---------- Main ----------
+def main():
+    parser = argparse.ArgumentParser(description="DINOv3 Patch Similarity Viewer (1 or 2 images; two-image shows BOTH overlays)")
+    # Accept either --image (single) or --image1/--image2 (two)
+    parser.add_argument("--image", type=str, default=None,
+                        help="Path/URL to image (single-image mode if only this is provided)")
+    parser.add_argument("--image1", type=str, default=None,
+                        help="Path/URL to first image (two-image mode if image2 is also provided)")
+    parser.add_argument("--image2", type=str, default=None,
+                        help="Path/URL to second image (two-image mode when given)")
+    parser.add_argument("--model", type=str, default=DEFAULT_MODEL_ID,
+                        help="DINOv3 model repo id (e.g., facebook/dinov3-vits16-pretrain-lvd1689m)")
+    parser.add_argument("--show_grid", action="store_true", help="Draw patch grid")
+    parser.add_argument("--annotate_indices", action="store_true", help="Write patch indices on cells")
+    parser.add_argument("--overlay_alpha", type=float, default=OVERLAY_ALPHA, help="Heatmap alpha")
+    parser.add_argument("--patch_size", type=int, default=(PATCH_SIZE_OVERRIDE or -1),
+                        help="Override patch size. Set 16 to force. Default: model's patch size")
+    args = parser.parse_args()
+
+    show_grid = args.show_grid or SHOW_GRID
+    annotate_indices = args.annotate_indices or ANNOTATE_INDICES
+    overlay_alpha = args.overlay_alpha
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"[info] Device: {device}")
+    model = AutoModel.from_pretrained(args.model).to(device)
+    model.eval()
+
+    def get_patch_size_from_model(model, default=16):
+        # Try to get patch size from model config if available
+        if hasattr(model, "config") and hasattr(model.config, "patch_size"):
+            ps = model.config.patch_size
+            if isinstance(ps, (tuple, list)):
+                return ps[0]
+            return ps
+        # Try to get from model attributes
+        if hasattr(model, "patch_size"):
+            ps = model.patch_size
+            if isinstance(ps, (tuple, list)):
+                return ps[0]
+            return ps
+        return default
+
+    ps = args.patch_size if args.patch_size and args.patch_size > 0 else get_patch_size_from_model(model, 16)
+    print(f"[info] Using patch size: {ps}")
+
+    # Routing logic:
+    img1 = args.image1 or args.image
+    img2 = args.image2
+
+    if img1 and img2:
+        run_two_images(img1, img2, model, device, ps, show_grid, annotate_indices, overlay_alpha)
+    else:
+        img_single = img1 or DEFAULT_URL
+        run_single_image(img_single, model, device, ps, show_grid, annotate_indices, overlay_alpha)
+
+if __name__ == "__main__":
+    main()

LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2023 [Your Name or Organization]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,14 +1,161 @@
----
-title: DINOv3 Interactive Patch Cosine Similarity
-emoji: 🏃
-colorFrom: yellow
-colorTo: gray
-sdk: gradio
-sdk_version: 5.43.1
-app_file: app.py
-pinned: false
-license: mit
-short_description: Interactive tool to visualize patch-wise similarity in image
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# DINOv3 Patch Similarity Viewer
+
+![Gradio Test app](assets/GradioAppTest.gif)
+
+> **Note:** This README and repository are for educational purposes. The creation of this repo was inspired by the DINOv3 paper to help visualize and understand the output of the model.
+
+## Purpose
+
+This repository provides interactive tools to visualize and explore patch-wise similarity in images using the DINOv3 vision transformer model. It is designed for researchers, students, and practitioners interested in understanding how self-supervised vision transformers perceive and relate different regions of an image.
+
+## About DINOv3
+
+- **Paper:** [DINOv3: Self-supervised Vision Transformers with Enormous Teacher Models](https://arxiv.org/abs/2508.10104)
+- **Meta Research Page:** [Meta DINOv3 Publication](https://ai.meta.com/dinov3/)
+- **Official GitHub:** [facebookresearch/dinov3](https://github.com/facebookresearch/dinov3)
+
+**Note:**  
+The DINOv3 model weights require access approval.  
+You can request access via the [Meta Research page](https://ai.meta.com/resources/models-and-libraries/dinov3-downloads/) or by selecting the desired model on [Hugging Face model collection](https://huggingface.co/collections/facebook/dinov3-68924841bd6b561778e31009).
+
+## Features
+
+- **Interactive Visualization:** Click on image patches or use arrow keys to explore patch similarity heatmaps.
+- **Single or Two-Image Mode:** If one image is specified, shows self-similarity. If two images are specified, shows both self-similarity and cross-image similarity overlays interactively.
+- **Image Preprocessing:** Loads and pads images without resizing, preserving the original aspect ratio.
+- **Cosine Similarity Calculation:** Computes and visualizes cosine similarity between image patches.
+- **Robust Fallback:** If an image URL fails to load, a default image is used.
+
+## Installation
+
+Install dependencies with:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Model Selection
+
+You can choose from several DINOv3 models available on Hugging Face (click to view each model card):
+
+LVD-1689M Dataset (Web data)
+- ViT
+    - [facebook/dinov3-vit7b16-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vit7b16-pretrain-lvd1689m)
+    - [facebook/dinov3-vits16-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vits16-pretrain-lvd1689m)
+    - [facebook/dinov3-vits16plus-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vits16plus-pretrain-lvd1689m)
+    - [facebook/dinov3-vitb16-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vitb16-pretrain-lvd1689m)
+    - [facebook/dinov3-vitl16-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m)
+    - [facebook/dinov3-vith16plus-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vith16plus-pretrain-lvd1689m)
+
+- ConvNeXt
+    - [facebook/dinov3-convnext-tiny-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-convnext-tiny-pretrain-lvd1689m)
+    - [facebook/dinov3-convnext-small-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-convnext-small-pretrain-lvd1689m)
+    - [facebook/dinov3-convnext-base-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-convnext-base-pretrain-lvd1689m)
+    - [facebook/dinov3-convnext-large-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-convnext-large-pretrain-lvd1689m)
+
+SAT-493M Dataset (Satellite data)
+- ViT
+    - [facebook/dinov3-vitl16-pretrain-sat493m](https://huggingface.co/facebook/dinov3-vitl16-pretrain-sat493m)
+    - [facebook/dinov3-vit7b16-pretrain-sat493m](https://huggingface.co/facebook/dinov3-vit7b16-pretrain-sat493m)
+
+## Usage
+
+### Gradio app
+
+Run the Gradio app:
+
+```bash
+python app.py
+```
+
+After runnig the app, go to [http://localhost:7860/](http://localhost:7860/) to see the app running.
+
+Then: 
+- Choose Dataset and model name
+- For Single image similarity:
+    - Choose only one file or URL
+- For 2 image similarity:
+    - Choose images from file and/or URL
+- Click button "Initialize / Update "
+- Select the desired patch from the image
+- Watch the results
+
+**Note:** 
+*Overlay alpha* is the intensity of the overlay of patches on top of image
+
+### Python Script
+
+Run the interactive viewer with the default COCO image:
+
+```bash
+python DINOv3CosSimilarity.py
+```
+
+#### Single Image Mode
+
+Specify your own image (local path or URL):
+
+```bash
+python DINOv3CosSimilarity.py --image path/to/your/image.jpg
+python DINOv3CosSimilarity.py --image https://yourdomain.com/image.png
+```
+
+#### Two Image Mode
+
+Specify two images (local paths or URLs):
+
+```bash
+python DINOv3CosSimilarity.py --image1 path/to/image1.jpg --image2 path/to/image2.jpg
+python DINOv3CosSimilarity.py --image1 https://yourdomain.com/image1.png --image2 https://yourdomain.com/image2.png
+```
+
+#### Model Selection
+
+Specify the model with `--model` (default is vits16):
+
+```bash
+python DINOv3CosSimilarity.py --model facebook/dinov3-vitb16-pretrain-lvd1689m
+```
+
+#### Other Options
+
+- `--show_grid` : Draw patch grid
+- `--annotate_indices` : Write patch indices on cells
+- `--overlay_alpha <float>` : Set heatmap alpha (default 0.55)
+- `--patch_size <int>` : Override patch size (default: model's patch size)
+
+#### Controls
+
+- Mouse click to select a patch
+- Arrow keys to move selection
+- '1', '2', or 't' to switch active image (in two-image mode)
+- 'q' to quit
+
+## Demo Single Image
+
+![Interactive Patch Similarity Demo](assets/Test_Interactive_video.gif)
+
+## Demo 2 Images
+
+![Multiple Interactive Patch Similarity Demo](assets/Multiple_Interactive_test_video.gif)
+
+### Jupyter Notebook
+
+1. Open `PatchCosSimilarity.ipynb` in Jupyter Notebook.
+2. Run the cells to load an image and visualize patch similarities.
+3. Set `url1` for single-image mode, or both `url1` and `url2` for two-image mode.
+4. If an image fails to load, a default image will be used automatically.
+5. Set the `model_id` variable to any of the models listed above (see commented lines at the top of the notebook).
+
+**Notebook Controls:**  
+- Mouse click to select a patch  
+- Arrow keys to move selection  
+- '1', '2', or 't' to switch active image (in two-image mode)
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.
+
+## Acknowledgments
+
+This project utilizes the DINOv3 model from Hugging Face's Transformers library, along with PyTorch, Matplotlib, and Pillow

app.py

@@ -0,0 +1,622 @@
+# app.py
+# Gradio UI for interactive DINOv3 patch similarity (single or dual image)
+# - No AutoImageProcessor, no resize (only pad to multiple of patch size)
+# - Single image: click to show self-similarity; selected cell outlined in RED
+# - Two images: click on one side -> self overlay on source, cross overlay on target; best match on target outlined in YELLOW
+# - Red selection rectangle is hidden on the non-active image
+# - Patch size inferred from model (no override). Patch indices are not annotated.
+# - Dataset selector (LVD-1689M / SAT-493M); model dropdown shows only the short name between "dinov3-" and "-pretrain".
+# - Sample URL dropdowns switch between LVD (COCO/Picsum) and SAT (satellite imagery) and auto-fill / clear uploads.
+
+import io
+import math
+import urllib.request
+from functools import lru_cache
+from typing import Optional, Tuple, Dict, List
+
+import gradio as gr
+import numpy as np
+from PIL import Image, ImageDraw
+import torch
+from torchvision import transforms
+from transformers import AutoModel
+from matplotlib import colormaps as cm
+
+# ---------- Provided model IDs (ground truth list) ----------
+MODEL_ID_LIST = [
+    "facebook/dinov3-vits16-pretrain-lvd1689m",
+    "facebook/dinov3-vits16plus-pretrain-lvd1689m",
+    "facebook/dinov3-vitb16-pretrain-lvd1689m",
+    "facebook/dinov3-vitl16-pretrain-lvd1689m",
+    "facebook/dinov3-vith16plus-pretrain-lvd1689m",
+    "facebook/dinov3-vit7b16-pretrain-lvd1689m",
+    "facebook/dinov3-convnext-tiny-pretrain-lvd1689m",
+    "facebook/dinov3-convnext-small-pretrain-lvd1689m",
+    "facebook/dinov3-convnext-base-pretrain-lvd1689m",
+    "facebook/dinov3-convnext-large-pretrain-lvd1689m",
+    "facebook/dinov3-vitl16-pretrain-sat493m",
+    "facebook/dinov3-vit7b16-pretrain-sat493m",
+]
+
+DATASET_LABELS = {
+    "LVD-1689M": "lvd1689m",
+    "SAT-493M": "sat493m",
+}
+
+def build_model_maps(model_ids: List[str]):
+    """
+    Returns:
+      valid_map[(dataset_key, short_name)] -> full_model_id
+      options_by_dataset[dataset_key] -> [short_name,...]  (display order preserved)
+    """
+    valid_map: Dict[Tuple[str, str], str] = {}
+    options_by_dataset: Dict[str, List[str]] = {"lvd1689m": [], "sat493m": []}
+
+    for mid in model_ids:
+        # Expect pattern: "facebook/dinov3-<short>-pretrain-<dataset>"
+        try:
+            prefix = "facebook/dinov3-"
+            start = mid.index(prefix) + len(prefix)
+            pre_idx = mid.index("-pretrain", start)
+            short = mid[start:pre_idx]
+            dataset = mid.split("-pretrain-")[-1].strip()
+        except Exception:
+            # Skip anything that doesn't match the expected pattern
+            continue
+
+        key = (dataset, short)
+        valid_map[key] = mid
+        if dataset in options_by_dataset and short not in options_by_dataset[dataset]:
+            options_by_dataset[dataset].append(short)
+
+    return valid_map, options_by_dataset
+
+VALID_MODEL_MAP, MODEL_OPTIONS_BY_DATASET = build_model_maps(MODEL_ID_LIST)
+
+# ---------- Defaults / knobs ----------
+DEFAULT_URL = "http://images.cocodataset.org/val2017/000000039769.jpg"
+DEFAULT_DATASET_LABEL = "LVD-1689M"  # initial radio
+DEFAULT_OVERLAY_ALPHA = 0.55
+DEFAULT_SHOW_GRID = True
+
+# ---------- Sample image URLs (dependent on dataset) ----------
+SAMPLE_URL_CHOICES: Dict[str, List[Tuple[str, str]]] = {
+    # LVD: current ones
+    "lvd1689m": [
+        ("– choose a sample –", ""),
+        ("COCO: 2 Cats on sofa (039769)", "http://images.cocodataset.org/val2017/000000039769.jpg"),
+        ("COCO: Person skiing (000785)", "http://images.cocodataset.org/val2017/000000000785.jpg"),
+        ("COCO: People running (000872)", "http://images.cocodataset.org/val2017/000000000872.jpg"),
+        ("Picsum: Mountain (ID=1000)", "https://picsum.photos/id/1000/800/600"),
+        ("Picsum: Kayak (ID=1011)", "https://picsum.photos/id/1011/800/600"),
+        ("Picsum: Man and dog (ID=1012)", "https://picsum.photos/id/1012/800/600"),
+    ],
+    # SAT: satellite imagery examples
+    "sat493m": [
+        ("– choose a satellite sample –", ""),
+        ("Blue Marble (NASA)", "https://upload.wikimedia.org/wikipedia/commons/9/9d/The_Blue_Marble_%28remastered%29.jpg"),
+        ("GOES-16 Hurricane Florence (2018)", "https://upload.wikimedia.org/wikipedia/commons/5/5e/Hurricane_Florence_GOES-16_2018-09-12_1510Z.jpg"),
+        ("NASA Earth Observatory: Philippines", "https://eoimages.gsfc.nasa.gov/images/imagerecords/151000/151639/philippines_tmo_2020118_lrg.jpg"),
+    ],
+}
+
+def _sample_labels_for(dataset_label: str):
+    key = DATASET_LABELS.get(dataset_label, "lvd1689m")
+    return [label for label, _ in SAMPLE_URL_CHOICES.get(key, [])]
+
+def _apply_sample(dataset_label: str, sample_label: str):
+    """Fill textbox with chosen sample URL and clear any uploaded image."""
+    key = DATASET_LABELS.get(dataset_label, "lvd1689m")
+    sample_map = dict(SAMPLE_URL_CHOICES.get(key, []))
+    url = sample_map.get(sample_label, "")
+    return gr.update(value=url), None  # (textbox update, clear upload)
+
+# ---------- Utility ----------
+def load_image_from_any(src: Optional[Image.Image], url: Optional[str]) -> Optional[Image.Image]:
+    # Prefer URL if present
+    if url and str(url).strip().lower().startswith(("http://", "https://")):
+        with urllib.request.urlopen(url) as resp:
+            data = resp.read()
+        return Image.open(io.BytesIO(data)).convert("RGB")
+    if isinstance(src, Image.Image):
+        return src.convert("RGB")
+    return None
+
+def pad_to_multiple(pil_img: Image.Image, multiple: int = 16) -> Tuple[Image.Image, Tuple[int, int, int, int]]:
+    W, H = pil_img.size
+    H_pad = int(math.ceil(H / multiple) * multiple)
+    W_pad = int(math.ceil(W / multiple) * multiple)
+    if (H_pad, W_pad) == (H, W):
+        return pil_img, (0, 0, 0, 0)
+    canvas = Image.new("RGB", (W_pad, H_pad), (0, 0, 0))
+    canvas.paste(pil_img, (0, 0))
+    return canvas, (0, 0, W_pad - W, H_pad - H)
+
+def preprocess_no_resize(pil_img: Image.Image, multiple: int = 16):
+    img_padded, pad_box = pad_to_multiple(pil_img, multiple=multiple)
+    transform = transforms.Compose([
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                             std =[0.229, 0.224, 0.225]),
+    ])
+    pixel_tensor = transform(img_padded).unsqueeze(0)  # (1,3,H,W)
+    disp_np = np.array(img_padded, dtype=np.uint8)
+    return {"pixel_values": pixel_tensor}, disp_np, pad_box
+
+def upsample_nearest(arr: np.ndarray, H: int, W: int, ps: int) -> np.ndarray:
+    if arr.ndim == 2:
+        return arr.repeat(ps, 0).repeat(ps, 1)
+    elif arr.ndim == 3:
+        rows, cols, ch = arr.shape
+        arr2 = arr.repeat(ps, 0).repeat(ps, 1)
+        return arr2.reshape(rows * ps, cols * ps, ch)
+    raise ValueError("upsample_nearest expects (rows,cols) or (rows,cols,channels)")
+
+def blend_overlay(base_uint8: np.ndarray, overlay_rgb_float: np.ndarray, alpha: float) -> np.ndarray:
+    base = base_uint8.astype(np.float32)
+    over = (overlay_rgb_float * 255.0).astype(np.float32)
+    out = (1.0 - alpha) * base + alpha * over
+    return np.clip(out, 0, 255).astype(np.uint8)
+
+def draw_grid(img: Image.Image, rows: int, cols: int, ps: int):
+    d = ImageDraw.Draw(img)
+    W, H = img.size
+    for r in range(1, rows):
+        y = r * ps
+        d.line([(0, y), (W, y)], fill=(255, 255, 255), width=1)
+    for c in range(1, cols):
+        x = c * ps
+        d.line([(x, 0), (x, H)], fill=(255, 255, 255), width=1)
+
+def rc_to_idx(r: int, c: int, cols: int) -> int:
+    return int(r) * cols + int(c)
+
+def idx_to_rc(i: int, cols: int) -> Tuple[int, int]:
+    return int(i) // cols, int(i) % cols
+
+# ---------- Model cache ----------
+@lru_cache(maxsize=3)
+def load_model_cached(full_model_id: str, device_str: str):
+    device = torch.device(device_str)
+    model = AutoModel.from_pretrained(full_model_id).to(device)
+    model.eval()
+    return model
+
+def infer_patch_size(model, default: int = 16) -> int:
+    if hasattr(model, "config") and hasattr(model.config, "patch_size"):
+        ps = model.config.patch_size
+        if isinstance(ps, (tuple, list)): return int(ps[0])
+        return int(ps)
+    if hasattr(model, "patch_size"):
+        ps = model.patch_size
+        if isinstance(ps, (tuple, list)): return int(ps[0])
+        return int(ps)
+    return default
+
+# ---------- Per-image state ----------
+class PatchImageState:
+    def __init__(self, pil_img: Image.Image, model, device_str: str, ps: int):
+        self.pil = pil_img
+        self.ps = ps
+        inputs, disp_np, _ = preprocess_no_resize(pil_img, multiple=ps)
+        self.disp = disp_np
+        pv = inputs["pixel_values"].to(device_str)  # (1,3,H,W)
+        _, _, H, W = pv.shape
+        self.H, self.W = int(H), int(W)
+        self.rows, self.cols = self.H // ps, self.W // ps
+
+        with torch.no_grad():
+            out = model(pixel_values=pv)
+        hs = out.last_hidden_state.squeeze(0).detach().cpu().numpy()  # (T,D)
+
+        T, D = hs.shape
+        n_patches = self.rows * self.cols
+        n_special = T - n_patches  # class + maybe registers
+        if n_special < 1:
+            raise RuntimeError(
+                f"Token mismatch: T={T}, rows*cols={n_patches}, HxW={self.H}x{self.W}, ps={ps}"
+            )
+        self.D = D
+        patches = hs[n_special:, :].reshape(self.rows, self.cols, D)
+        self.X = patches.reshape(-1, D)
+        self.Xn = self.X / (np.linalg.norm(self.X, axis=1, keepdims=True) + 1e-8)
+
+# ---------- Rendering / compute ----------
+def render_with_cosmap(
+    st: PatchImageState,
+    cos_map: Optional[np.ndarray],
+    overlay_alpha: float,
+    show_grid_flag: bool,
+    select_idx: Optional[int] = None,
+    best_idx: Optional[int] = None,
+) -> Image.Image:
+    H, W, ps = st.H, st.W, st.ps
+    rows, cols = st.rows, st.cols
+
+    if cos_map is None:
+        disp = np.full((rows, cols), 0.5, dtype=np.float32)
+    else:
+        vmin, vmax = float(cos_map.min()), float(cos_map.max())
+        rng = vmax - vmin if vmax > vmin else 1e-8
+        disp = (cos_map - vmin) / rng
+
+    cmap = cm.get_cmap("magma")
+    rgba = cmap(disp)
+    rgb = rgba[..., :3]
+
+    if select_idx is not None:
+        rs, cs = idx_to_rc(select_idx, cols)
+        rgb[rs, cs, :] = np.array([1.0, 0.0, 0.0], dtype=np.float32)
+
+    over_rgb_up = upsample_nearest(rgb, H, W, ps)
+    blended = blend_overlay(st.disp, over_rgb_up, float(overlay_alpha))
+    pil = Image.fromarray(blended)
+
+    draw = ImageDraw.Draw(pil)
+    if show_grid_flag:
+        draw_grid(pil, rows, cols, ps)
+
+    if select_idx is not None:
+        r, c = idx_to_rc(select_idx, cols)
+        x0, y0 = c * ps, r * ps
+        x1, y1 = x0 + ps - 1, y0 + ps - 1
+        draw.rectangle([(x0, y0), (x1, y1)], outline=(255, 0, 0), width=2)
+
+    if best_idx is not None:
+        r, c = idx_to_rc(best_idx, cols)
+        x0, y0 = c * ps, r * ps
+        x1, y1 = x0 + ps - 1, y0 + ps - 1
+        draw.rectangle([(x0, y0), (x1, y1)], outline=(255, 255, 0), width=2)
+
+    return pil
+
+def compute_self_and_cross(
+    src: PatchImageState,
+    tgt: Optional[PatchImageState],
+    q_idx: int,
+):
+    q = src.X[q_idx]
+    qn = q / (np.linalg.norm(q) + 1e-8)
+
+    cos_self = src.Xn @ qn
+    cos_map_self = cos_self.reshape(src.rows, src.cols)
+    self_stats = (float(cos_map_self.min()), float(cos_map_self.max()))
+
+    cross_result = None
+    cos_map_cross = None
+    if tgt is not None:
+        cos_cross = tgt.Xn @ qn
+        cos_map_cross = cos_cross.reshape(tgt.rows, tgt.cols)
+        cross_min, cross_max = float(cos_map_cross.min()), float(cos_map_cross.max())
+        best_idx = int(np.argmax(cos_cross))
+        cross_result = (cross_min, cross_max, best_idx)
+
+    return cos_map_self, cos_map_cross, self_stats, cross_result
+
+# ---------- Gradio helpers for model & samples ----------
+def dataset_label_to_key(label: str) -> str:
+    return DATASET_LABELS.get(label, "lvd1689m")
+
+def update_model_dropdown(dataset_label: str):
+    key = dataset_label_to_key(dataset_label)
+    opts = MODEL_OPTIONS_BY_DATASET.get(key, [])
+    default_val = opts[0] if opts else None
+    return gr.update(choices=opts, value=default_val)
+
+def update_model_and_samples(dataset_label: str):
+    # Update model dropdown
+    model_update = update_model_dropdown(dataset_label)
+    # Update both sample dropdowns to dataset-specific options
+    labels = _sample_labels_for(dataset_label)
+    sample_update = gr.update(choices=labels, value=(labels[0] if labels else None))
+    return model_update, sample_update, sample_update
+
+def resolve_full_model_id(dataset_label: str, short_name: str) -> Optional[str]:
+    key = (dataset_label_to_key(dataset_label), short_name)
+    return VALID_MODEL_MAP.get(key)
+
+# ---------- Gradio callbacks ----------
+def init_states(
+    left_img_in: Optional[Image.Image],
+    left_url: str,
+    right_img_in: Optional[Image.Image],
+    right_url: str,
+    dataset_label: str,
+    short_model: str,
+    show_grid_flag: bool,
+    overlay_alpha: float,
+):
+    # Resolve images
+    left_img = load_image_from_any(left_img_in, left_url)
+    right_img = load_image_from_any(right_img_in, right_url)
+    if left_img is None and right_img is None:
+        left_img = load_image_from_any(None, DEFAULT_URL)
+
+    # Resolve model
+    full_model_id = resolve_full_model_id(dataset_label, short_model)
+    if not full_model_id:
+        return (gr.update(), gr.update(), None, None, 0, -1, -1, 16,
+                f"❌ Model not available: {dataset_label} / {short_model}")
+
+    device_str = "cuda" if torch.cuda.is_available() else "cpu"
+    model = load_model_cached(full_model_id, device_str)
+    ps = infer_patch_size(model, 16)
+
+    left_state = PatchImageState(left_img, model, device_str, ps) if left_img is not None else None
+    right_state = PatchImageState(right_img, model, device_str, ps) if right_img is not None else None
+
+    active_side = 0 if left_state is not None else 1
+
+    status = f"✔ Loaded: {full_model_id}  |  ps={ps}"
+    out_left, out_right = None, None
+
+    if left_state is not None and right_state is not None:
+        q_idx = (left_state.rows // 2) * left_state.cols + (left_state.cols // 2)
+        cos_self, cos_cross, (smin, smax), cross_info = compute_self_and_cross(left_state, right_state, q_idx)
+        best_idx = cross_info[2] if cross_info else None
+        out_left = render_with_cosmap(left_state, cos_self, overlay_alpha, show_grid_flag,
+                                      select_idx=q_idx, best_idx=None)
+        out_right = render_with_cosmap(right_state, cos_cross, overlay_alpha, show_grid_flag,
+                                       select_idx=None, best_idx=best_idx)
+        status += (f"  |  LEFT {left_state.rows}x{left_state.cols} self∈[{smin:.3f},{smax:.3f}]  "
+                   f"|  RIGHT cross best={best_idx}")
+        left_idx, right_idx = q_idx, (right_state.rows // 2) * right_state.cols + (right_state.cols // 2)
+    elif left_state is not None:
+        q_idx = (left_state.rows // 2) * left_state.cols + (left_state.cols // 2)
+        cos_self, _, (smin, smax), _ = compute_self_and_cross(left_state, None, q_idx)
+        out_left = render_with_cosmap(left_state, cos_self, overlay_alpha, show_grid_flag,
+                                      select_idx=q_idx, best_idx=None)
+        status += f"  |  Single LEFT {left_state.rows}x{left_state.cols} self∈[{smin:.3f},{smax:.3f}]"
+        left_idx, right_idx = q_idx, -1
+    else:
+        q_idx = (right_state.rows // 2) * right_state.cols + (right_state.cols // 2)
+        cos_self, _, (smin, smax), _ = compute_self_and_cross(right_state, None, q_idx)
+        out_right = render_with_cosmap(right_state, cos_self, overlay_alpha, show_grid_flag,
+                                       select_idx=q_idx, best_idx=None)
+        status += f"  |  Single RIGHT {right_state.rows}x{right_state.cols} self∈[{smin:.3f},{smax:.3f}]"
+        left_idx, right_idx = -1, q_idx
+
+    return (
+        out_left, out_right,
+        left_state, right_state,
+        active_side,
+        left_idx, right_idx,
+        ps,
+        status
+    )
+
+def _coords_to_idx(x: int, y: int, st: PatchImageState) -> int:
+    r = int(np.clip(y // st.ps, 0, st.rows - 1))
+    c = int(np.clip(x // st.ps, 0, st.cols - 1))
+    return rc_to_idx(r, c, st.cols)
+
+def on_select_left(
+    evt: gr.SelectData,
+    left_state: Optional[PatchImageState],
+    right_state: Optional[PatchImageState],
+    show_grid_flag: bool,
+    overlay_alpha: float,
+    ps: int,
+):
+    if left_state is None:
+        return gr.update(), gr.update(), 0, -1, -1, "Upload/Load a LEFT image first."
+
+    x, y = evt.index
+    q_idx = _coords_to_idx(x, y, left_state)
+
+    if right_state is not None:
+        cos_self, cos_cross, (smin, smax), cross_info = compute_self_and_cross(left_state, right_state, q_idx)
+        best_idx = cross_info[2]
+        out_left = render_with_cosmap(left_state, cos_self, overlay_alpha, show_grid_flag,
+                                      select_idx=q_idx, best_idx=None)
+        out_right = render_with_cosmap(right_state, cos_cross, overlay_alpha, show_grid_flag,
+                                       select_idx=None, best_idx=best_idx)
+        status = (f"LEFT {left_state.rows}x{left_state.cols} self∈[{smin:.3f},{smax:.3f}]  |  "
+                  f"RIGHT cross best idx={best_idx}")
+        return out_left, out_right, 0, q_idx, -1, status
+    else:
+        cos_self, _, (smin, smax), _ = compute_self_and_cross(left_state, None, q_idx)
+        out_left = render_with_cosmap(left_state, cos_self, overlay_alpha, show_grid_flag,
+                                      select_idx=q_idx, best_idx=None)
+        status = f"Single LEFT • idx={q_idx} • self∈[{smin:.3f},{smax:.3f}]"
+        return out_left, gr.update(), 0, q_idx, -1, status
+
+def on_select_right(
+    evt: gr.SelectData,
+    left_state: Optional[PatchImageState],
+    right_state: Optional[PatchImageState],
+    show_grid_flag: bool,
+    overlay_alpha: float,
+    ps: int,
+):
+    if right_state is None:
+        return gr.update(), gr.update(), 1, -1, -1, "Upload/Load a RIGHT image first."
+
+    x, y = evt.index
+    q_idx = _coords_to_idx(x, y, right_state)
+
+    if left_state is not None:
+        cos_self, cos_cross, (smin, smax), cross_info = compute_self_and_cross(right_state, left_state, q_idx)
+        best_idx = cross_info[2]
+        out_right = render_with_cosmap(right_state, cos_self, overlay_alpha, show_grid_flag,
+                                       select_idx=q_idx, best_idx=None)
+        out_left = render_with_cosmap(left_state, cos_cross, overlay_alpha, show_grid_flag,
+                                      select_idx=None, best_idx=best_idx)
+        status = (f"RIGHT {right_state.rows}x{right_state.cols} self∈[{smin:.3f},{smax:.3f}]  |  "
+                  f"LEFT cross best idx={best_idx}")
+        return out_left, out_right, 1, -1, q_idx, status
+    else:
+        cos_self, _, (smin, smax), _ = compute_self_and_cross(right_state, None, q_idx)
+        out_right = render_with_cosmap(right_state, cos_self, overlay_alpha, show_grid_flag,
+                                       select_idx=q_idx, best_idx=None)
+        status = f"Single RIGHT • idx={q_idx} • self∈[{smin:.3f},{smax:.3f}]"
+        return gr.update(), out_right, 1, -1, q_idx, status
+
+def rebuild_with_settings(
+    left_state: Optional[PatchImageState],
+    right_state: Optional[PatchImageState],
+    active_side: int,
+    left_idx: int,
+    right_idx: int,
+    show_grid_flag: bool,
+    overlay_alpha: float,
+    ps: int,
+):
+    if left_state is None and right_state is None:
+        return gr.update(), gr.update(), "Load an image first."
+
+    if left_state is not None and right_state is not None:
+        if active_side == 0:
+            q_idx = left_idx if left_idx >= 0 else (left_state.rows//2)*left_state.cols + (left_state.cols//2)
+            cos_self, cos_cross, _, cross_info = compute_self_and_cross(left_state, right_state, q_idx)
+            best_idx = cross_info[2]
+            out_left = render_with_cosmap(left_state, cos_self, overlay_alpha, show_grid_flag,
+                                          select_idx=q_idx, best_idx=None)
+            out_right = render_with_cosmap(right_state, cos_cross, overlay_alpha, show_grid_flag,
+                                           select_idx=None, best_idx=best_idx)
+        else:
+            q_idx = right_idx if right_idx >= 0 else (right_state.rows//2)*right_state.cols + (right_state.cols//2)
+            cos_self, cos_cross, _, cross_info = compute_self_and_cross(right_state, left_state, q_idx)
+            best_idx = cross_info[2]
+            out_right = render_with_cosmap(right_state, cos_self, overlay_alpha, show_grid_flag,
+                                           select_idx=q_idx, best_idx=None)
+            out_left = render_with_cosmap(left_state, cos_cross, overlay_alpha, show_grid_flag,
+                                          select_idx=None, best_idx=best_idx)
+        return out_left, out_right, "Updated overlays."
+    elif left_state is not None:
+        q_idx = left_idx if left_idx >= 0 else (left_state.rows//2)*left_state.cols + (left_state.cols//2)
+        cos_self, _, _, _ = compute_self_and_cross(left_state, None, q_idx)
+        out_left = render_with_cosmap(left_state, cos_self, overlay_alpha, show_grid_flag,
+                                      select_idx=q_idx, best_idx=None)
+        return out_left, gr.update(), "Updated overlays."
+    else:
+        q_idx = right_idx if right_idx >= 0 else (right_state.rows//2)*right_state.cols + (right_state.cols//2)
+        cos_self, _, _, _ = compute_self_and_cross(right_state, None, q_idx)
+        out_right = render_with_cosmap(right_state, cos_self, overlay_alpha, show_grid_flag,
+                                       select_idx=q_idx, best_idx=None)
+        return gr.update(), out_right, "Updated overlays."
+
+# ---------- Gradio UI ----------
+with gr.Blocks(title="DINOv3 Patch Similarity (Self & Cross)") as demo:
+    gr.Markdown(
+        """
+        # DINOv3 Patch Similarity (Self & Cross)
+        1) Pick **Dataset** (LVD-1689M / SAT-493M).  
+        2) Pick **Model**.  
+        3) Upload one or two images (or paste URLs) and press **Initialize / Update**.  
+        - Click on a patch to update overlays.  
+        - In two-image mode, the non-active image hides the red selection and shows **yellow** best match.
+        """
+    )
+
+    with gr.Row():
+        dataset_radio = gr.Radio(
+            label="Dataset",
+            choices=list(DATASET_LABELS.keys()),
+            value=DEFAULT_DATASET_LABEL,
+            interactive=True
+        )
+        initial_key = DATASET_LABELS[DEFAULT_DATASET_LABEL]
+        initial_models = MODEL_OPTIONS_BY_DATASET.get(initial_key, [])
+        model_dropdown = gr.Dropdown(
+            label="Model name",
+            choices=initial_models,
+            value=(initial_models[0] if initial_models else None),
+            interactive=True
+        )
+
+    # initial sample labels based on default dataset
+    initial_sample_labels = [label for label, _ in SAMPLE_URL_CHOICES.get(initial_key, [])]
+
+    with gr.Row():
+        with gr.Column():
+            left_input = gr.Image(label="Left Image (upload)", type="pil",
+                                  sources=["upload", "clipboard", "webcam"], interactive=True)
+            left_url = gr.Textbox(label="Left Image URL (optional)", placeholder="https://...")
+            left_sample = gr.Dropdown(label="Use a sample URL",
+                                      choices=initial_sample_labels,
+                                      value=(initial_sample_labels[0] if initial_sample_labels else None),
+                                      interactive=True)
+        with gr.Column():
+            right_input = gr.Image(label="Right Image (upload)", type="pil",
+                                   sources=["upload", "clipboard", "webcam"], interactive=True)
+            right_url = gr.Textbox(label="Right Image URL (optional)", placeholder="https://...")
+            right_sample = gr.Dropdown(label="Use a sample URL",
+                                       choices=initial_sample_labels,
+                                       value=(initial_sample_labels[0] if initial_sample_labels else None),
+                                       interactive=True)
+
+    with gr.Accordion("Overlay Settings", open=True):
+        show_grid = gr.Checkbox(label="Show patch grid", value=DEFAULT_SHOW_GRID)
+        overlay_alpha = gr.Slider(label="Overlay alpha", minimum=0.0, maximum=1.0,
+                                  value=DEFAULT_OVERLAY_ALPHA, step=0.01)
+
+    init_btn = gr.Button("Initialize / Update", variant="primary")
+
+    with gr.Row():
+        left_view = gr.Image(label="LEFT (click to select patch)", interactive=True)
+        right_view = gr.Image(label="RIGHT (click to select patch)", interactive=True)
+
+    status = gr.Markdown("")
+
+    # Hidden states
+    left_state = gr.State(None)
+    right_state = gr.State(None)
+    active_side = gr.State(0)
+    left_idx = gr.State(-1)
+    right_idx = gr.State(-1)
+    ps_state = gr.State(16)
+
+    # Update model dropdown and sample lists when dataset changes
+    dataset_radio.change(
+        fn=update_model_and_samples,
+        inputs=[dataset_radio],
+        outputs=[model_dropdown, left_sample, right_sample]
+    )
+
+    # When a sample is chosen, set URL and clear any uploaded image (prefer URL)
+    left_sample.change(
+        fn=_apply_sample,
+        inputs=[dataset_radio, left_sample],
+        outputs=[left_url, left_input]
+    )
+    right_sample.change(
+        fn=_apply_sample,
+        inputs=[dataset_radio, right_sample],
+        outputs=[right_url, right_input]
+    )
+
+    # Initialize / reload model + overlays
+    init_btn.click(
+        fn=init_states,
+        inputs=[left_input, left_url, right_input, right_url, dataset_radio, model_dropdown, show_grid, overlay_alpha],
+        outputs=[left_view, right_view, left_state, right_state, active_side, left_idx, right_idx, ps_state, status],
+        show_progress=True
+    )
+
+    # Click handlers
+    left_view.select(
+        fn=on_select_left,
+        inputs=[left_state, right_state, show_grid, overlay_alpha, ps_state],
+        outputs=[left_view, right_view, active_side, left_idx, right_idx, status]
+    )
+    right_view.select(
+        fn=on_select_right,
+        inputs=[left_state, right_state, show_grid, overlay_alpha, ps_state],
+        outputs=[left_view, right_view, active_side, left_idx, right_idx, status]
+    )
+
+    # Live re-render on setting changes
+    show_grid.change(
+        fn=rebuild_with_settings,
+        inputs=[left_state, right_state, active_side, left_idx, right_idx, show_grid, overlay_alpha, ps_state],
+        outputs=[left_view, right_view, status]
+    )
+    overlay_alpha.change(
+        fn=rebuild_with_settings,
+        inputs=[left_state, right_state, active_side, left_idx, right_idx, show_grid, overlay_alpha, ps_state],
+        outputs=[left_view, right_view, status]
+    )
+
+if __name__ == "__main__":
+    demo.queue().launch()

requirements.txt

@@ -0,0 +1,10 @@
+torch
+torchvision
+matplotlib
+numpy==1.26.4
+ipykernel
+ipywidgets
+ipympl
+
+# Install Transformers directly from GitHub source
+transformers @ git+https://github.com/huggingface/transformers.git