deploy 1.0

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

README.md

@@ -11,4 +11,138 @@ license: mit
 short_description: To run EchoTracker instantly on a custom or given videos.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🫀 EchoTracker
+
+**Advancing Myocardial Point Tracking in Echocardiography**
+
+[![MICCAI 2024](https://img.shields.io/badge/MICCAI-2024-blue)](https://link.springer.com/chapter/10.1007/978-3-031-72083-3_60)
+[![arXiv](https://img.shields.io/badge/arXiv-2405.08587-red)](https://arxiv.org/abs/2405.08587)
+[![GitHub](https://img.shields.io/badge/GitHub-riponazad%2Fechotracker-black)](https://github.com/riponazad/echotracker)
+[![Project Page](https://img.shields.io/badge/Project-Page-purple)](https://riponazad.github.io/echotracker/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+EchoTracker is an interactive demo for tracking user-selected points on cardiac tissue across echocardiography video sequences. It was presented at **MICCAI 2024** and demonstrates strong generalisation across cardiac views and scanner types — including out-of-distribution settings not seen during training.
+
+---
+
+## Demo
+
+Try the live demo on Hugging Face Spaces: [EchoTracker Space](https://huggingface.co/spaces/riponazad/echotracker)
+
+---
+
+## Features
+
+- **Interactive point selection** — click directly on a video frame to place up to 100 tracking points on cardiac structures (e.g. LV/RV walls, myocardium)
+- **Frame navigation** — scrub through frames with a slider to choose the optimal query frame (end-diastolic recommended)
+- **Multi-view support** — handles A4C (apical 4-chamber), RV (right ventricle), and PSAX (parasternal short-axis) views
+- **Out-of-distribution (OOD) generalisation** — tested on scanner types and views not seen during training
+- **Faded trajectory visualisation** — output video overlays colour-coded tracks with fade-trail rendering
+- **Built-in examples** — four bundled clips (A4C, A4C OOD, RV OOD, PSAX OOD) for instant testing
+
+---
+
+## How to Use
+
+1. **Load a video** — upload your own echocardiography clip or click one of the provided example thumbnails.
+2. **Navigate to the query frame** — use the frame slider to find the desired starting frame. The end-diastolic frame is recommended for best results.
+3. **Place tracking points** — click anywhere on the frame image to add a point. Up to **100 points** are supported per run.
+4. **Adjust selection** — use **Undo** to remove the last point or **Clear All** to start over.
+5. **Run the tracker** — press **▶ Run EchoTracker** to generate trajectories for all selected points.
+6. **View output** — the annotated video with colour-coded tracks appears in the output player.
+
+> **Tip:** Points are stored as `(x, y)` pixel coordinates on the original frame and are automatically rescaled to the model's 256 × 256 input resolution.
+
+---
+
+## Running Locally
+
+### Prerequisites
+
+- Python 3.10+
+- A CUDA-capable GPU (optional but recommended; CPU inference is supported)
+
+### Installation
+
+```bash
+git clone https://github.com/riponazad/echotracker.git
+cd echotracker
+pip install gradio torch opencv-python-headless numpy Pillow mediapy scikit-image
+```
+
+### Launch
+
+```bash
+python app.py
+```
+
+The Gradio interface will be available at `http://localhost:7860`.
+
+### Model Weights
+
+The pre-trained TorchScript model (`echotracker_cvamd_ts.pt`) must be present in the project root. It is included in this repository/Space and loaded automatically at startup.
+
+---
+
+## Repository Structure
+
+```
+echotracker/
+├── app.py                    # Gradio application and UI
+├── utils.py                  # Point-to-tensor conversion and tracking visualisation
+├── echotracker_cvamd_ts.pt   # Pre-trained TorchScript model weights
+├── example_samples/          # Bundled example echocardiography clips
+│   ├── input1.mp4            # A4C view
+│   ├── input2.mp4            # A4C view (OOD)
+│   ├── input3_RV.mp4         # RV view (OOD)
+│   └── psax_video_crop.mp4   # PSAX view (OOD)
+└── outputs/                  # Saved tracking output videos
+```
+
+---
+
+## Technical Details
+
+| Property | Value |
+|---|---|
+| Model format | TorchScript (`.pt`) |
+| Input resolution | 256 × 256 (grayscale) |
+| Max tracking points | 100 |
+| Output video FPS | 25 |
+| Supported views | A4C, RV, PSAX |
+| Device | CUDA (auto) or CPU |
+
+The tracker receives a batch of grayscale frames of shape `[B, T, 1, H, W]` and a set of query points `[B, N, 3]` (frame index, x, y). It returns per-point trajectories that are denormalised and overlaid on the original-resolution frames.
+
+---
+
+## Citation
+
+If you use EchoTracker in your research, please cite:
+
+```bibtex
+@InProceedings{azad2024echotracker,
+    author    = {Azad, Md Abulkalam and Chernyshov, Artem and Nyberg, John
+                 and Tveten, Ingrid and Lovstakken, Lasse and Dalen, H{\aa}vard
+                 and Grenne, Bj{\o}rnar and {\O}stvik, Andreas},
+    title     = {EchoTracker: Advancing Myocardial Point Tracking in Echocardiography},
+    booktitle = {Medical Image Computing and Computer Assisted Intervention -- MICCAI 2024},
+    year      = {2024},
+    publisher = {Springer Nature Switzerland},
+    doi       = {10.1007/978-3-031-72083-3_60}
+}
+```
+
+---
+
+## Authors
+
+Md Abulkalam Azad, Artem Chernyshov, John Nyberg, Ingrid Tveten, Lasse Lovstakken, Håvard Dalen, Bjørnar Grenne, Andreas Østvik
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+> **Note:** The bundled example echocardiography clips are provided for demonstration purposes only and should not be downloaded, reproduced, or used outside this demo.

app.py

@@ -0,0 +1,573 @@
+import gradio as gr
+import os
+import torch
+import cv2
+import numpy as np
+import random
+from PIL import Image
+from utils import points_to_tensor
+from utils import visualize_tracking
+import mediapy as media
+
+# ── Colormap (matches your viz_utils.get_colors logic) ───────────────────────
+def get_colors(n):
+    """Generate n random but unique colors in RGB 0-255."""
+    random.seed(42)  # remove this line if you want different colors each run
+    
+    # Spread hues evenly across 0-179 (HSV in OpenCV), then shuffle
+    hues = list(range(0, 180, max(1, 180 // n)))[:n]
+    random.shuffle(hues)
+    
+    colors = []
+    for hue in hues:
+        # Randomize saturation and value slightly for more visual variety
+        sat = random.randint(180, 255)
+        val = random.randint(180, 255)
+        hsv = np.uint8([[[hue, sat, val]]])
+        rgb = cv2.cvtColor(hsv, cv2.COLOR_HSV2RGB)[0][0]
+        colors.append(tuple(int(c) for c in rgb))
+    
+    return colors
+
+N_POINTS  = 100
+COLORMAP  = get_colors(N_POINTS)
+select_points = []   # will hold np.array([x, y]) entries
+
+# ── Video helpers ─────────────────────────────────────────────────────────────
+def get_frame(video_path: str, frame_idx: int) -> np.ndarray:
+    """Extract a single frame from video by index."""
+    cap = cv2.VideoCapture(video_path)
+    cap.set(cv2.CAP_PROP_POS_FRAMES, frame_idx)
+    ret, frame = cap.read()
+    cap.release()
+    if not ret:
+        raise ValueError(f"Could not read frame {frame_idx}")
+    return cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+
+def get_total_frames(video_path: str) -> int:
+    cap = cv2.VideoCapture(video_path)
+    total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    cap.release()
+    return total
+
+# ── Draw points on frame ──────────────────────────────────────────────────────
+def draw_points(frame: np.ndarray, points: list) -> np.ndarray:
+    """Draw colored circle markers on frame for each selected point."""
+    out = frame.copy()
+    for i, pt in enumerate(points):
+        color = COLORMAP[i % N_POINTS]          # RGB tuple
+        bgr   = (color[2], color[1], color[0])  # cv2 uses BGR
+        cv2.circle(out, (pt[0], pt[1]), radius=6,
+                   color=bgr, thickness=-1)
+        cv2.circle(out, (pt[0], pt[1]), radius=6,
+                   color=(255, 255, 255), thickness=2)  # white border
+        cv2.putText(out, str(i + 1), (pt[0] + 10, pt[1] - 6),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)
+    return out
+
+_SAMPLES_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "example_samples")
+
+# JS injected into gr.Blocks — controls download availability on video players
+_DOWNLOAD_CTRL_JS = """
+(function () {
+  const EXAMPLE_IDS = ['video_upload_player', 'out_video_player'];
+  const USER_IDS    = ['out_video_player'];
+
+  function applyNoDownload(ids) {
+    ids.forEach(function (id) {
+      var el = document.getElementById(id);
+      if (!el) return;
+      el.querySelectorAll('video').forEach(function (v) {
+        v.setAttribute('controlsList', 'nodownload');
+        v.oncontextmenu = function (e) { e.preventDefault(); };
+      });
+      el.querySelectorAll('a').forEach(function (a) {
+        a.style.cssText = 'display:none!important;pointer-events:none!important';
+      });
+      el.querySelectorAll('button').forEach(function (btn) {
+        var lbl = (btn.getAttribute('aria-label') || btn.getAttribute('title') || '').toLowerCase();
+        if (lbl.includes('download') || lbl.includes('save')) {
+          btn.style.cssText = 'display:none!important;pointer-events:none!important';
+        }
+      });
+    });
+  }
+
+  function clearNoDownload(ids) {
+    ids.forEach(function (id) {
+      var el = document.getElementById(id);
+      if (!el) return;
+      el.querySelectorAll('video').forEach(function (v) {
+        v.removeAttribute('controlsList');
+        v.oncontextmenu = null;
+      });
+      el.querySelectorAll('a').forEach(function (a) { a.style.cssText = ''; });
+      el.querySelectorAll('button').forEach(function (btn) { btn.style.cssText = ''; });
+    });
+  }
+
+  window._isExampleMode = false;
+
+  function applyCurrentMode() {
+    if (window._isExampleMode) applyNoDownload(EXAMPLE_IDS);
+    else clearNoDownload(USER_IDS);
+  }
+
+  /* Watch both containers for DOM changes (e.g. when video src updates) */
+  EXAMPLE_IDS.concat(['out_video_player']).forEach(function (id) {
+    (function tryObserve() {
+      var el = document.getElementById(id);
+      if (!el) { setTimeout(tryObserve, 400); return; }
+      new MutationObserver(applyCurrentMode)
+        .observe(el, { childList: true, subtree: true });
+    })();
+  });
+
+  /* Intercept value setter on hidden textbox to receive mode signal from Python */
+  function hookTrigger() {
+    var container = document.querySelector('#download_ctrl textarea');
+    if (!container) { setTimeout(hookTrigger, 300); return; }
+    var desc = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value');
+    Object.defineProperty(container, 'value', {
+      get: function ()  { return desc.get.call(this); },
+      set: function (v) {
+        desc.set.call(this, v);
+        window._isExampleMode = (v === '1');
+        applyCurrentMode();
+      },
+      configurable: true,
+    });
+  }
+
+  setTimeout(hookTrigger, 500);
+})();
+"""
+# label → (path, is_ood)
+EXAMPLE_VIDEOS = {
+    "A4C":          (os.path.join(_SAMPLES_DIR, "input1.mp4"),          False),
+    "A4C (OOD)":    (os.path.join(_SAMPLES_DIR, "input2.mp4"),          True),
+    "RV (OOD)":     (os.path.join(_SAMPLES_DIR, "input3_RV.mp4"),       True),
+    "PSAX (OOD)":   (os.path.join(_SAMPLES_DIR, "psax_video_crop.mp4"), True),
+}
+
+def _get_thumbnail(video_path: str) -> np.ndarray | None:
+    """Extract a single frame near the middle of the video for use as a thumbnail."""
+    try:
+        cap = cv2.VideoCapture(video_path)
+        total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        cap.set(cv2.CAP_PROP_POS_FRAMES, max(0, int(total * 0.4)))
+        ret, frame = cap.read()
+        cap.release()
+        if ret:
+            return cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+    except Exception:
+        pass
+    return None
+
+THUMBNAILS = {label: _get_thumbnail(path) for label, (path, _) in EXAMPLE_VIDEOS.items()}
+
+# ── Gradio event handlers ─────────────────────────────────────────────────────
+def on_video_upload(video_path):
+    """Called when video is uploaded — jump to 72% frame."""
+    if video_path is None:
+        # return None, gr.update(value=0, maximum=0, interactive=False), "No video loaded.", []
+        return None
+
+    total  = get_total_frames(video_path)
+    idx_72 = int(total * 0.72)
+
+    frame  = get_frame(video_path, idx_72)
+    #drawn  = draw_points(frame, select_points)
+
+    frame_display_update = gr.update(
+        value=frame,
+        interactive=True, # enables click events via gr.SelectData
+    )
+
+    slider_update = gr.update(
+        value=idx_72,
+        minimum=0,
+        maximum=total - 1,
+        step=1,
+        interactive=True,
+        label=f"Frame selector  (total: {total} frames)"
+    )
+
+    select_points.clear()   # clear any existing points when new video is loaded
+
+    status = f"📹 Loaded — {total} frames | 🎞️ Showing frame {idx_72} (72%)"
+    # last value resets the download-control style (user upload → downloads allowed)
+    return frame_display_update, slider_update, status, video_path, ""
+
+def load_example(video_path):
+    """Load an example video, reset all output/selection fields, and hide downloads."""
+    frame_upd, slider_upd, status, state, _ = on_video_upload(video_path)
+    return (
+        gr.update(value=video_path),   # video_upload
+        frame_upd,                     # frame_display
+        slider_upd,                    # frame_slider
+        status,                        # status_text
+        state,                         # video_state
+        gr.update(value=None),         # out_video  — clear previous result
+        gr.update(value="No points selected yet."),  # points_display
+        "1",                           # download_ctrl — disable downloads
+    )
+
+def on_slider_release(frame_idx, video_path, points_display):
+    """Called when slider is released — show new frame, keep existing points."""
+    if video_path is None:
+        return None, "No video loaded.", points_display
+    frame  = get_frame(video_path, int(frame_idx))
+    select_points.clear()   # clear any existing points when new video is loaded
+    #print(f"Selected point: {select_points}")
+    points_display = gr.update(
+                value="No points selected yet.",
+                label="📋 Selected Points",
+                lines=5,
+                interactive=False,
+            )
+    #drawn  = draw_points(frame, select_points)
+    status = f"🎞️ Showing Frame {int(frame_idx)} ({int(frame_idx) / get_total_frames(video_path) * 100:.1f}%) | {len(select_points)} point(s) selected"
+    return frame, status, points_display
+
+def on_point_select(frame_idx, video_path, evt: gr.SelectData):
+    """Called when user clicks on the image — add point, redraw."""
+    if video_path is None:
+        return None, "Upload a video first.", format_points()
+
+    if len(select_points) >= N_POINTS:
+        status = f"⚠️ Max {N_POINTS} points reached."
+        frame  = get_frame(video_path, int(frame_idx))
+        return draw_points(frame, select_points), status, format_points()
+
+    x, y = int(evt.index[0]), int(evt.index[1])
+    select_points.append(np.array([x, y]))
+
+    #print(f"Selected point: {select_points}")
+
+    frame  = get_frame(video_path, int(frame_idx))
+    drawn  = draw_points(frame, select_points)
+    status = f"✅ Point {len(select_points)} added at ({x}, {y}) | Frame {int(frame_idx)}"
+    return drawn, status, format_points()
+
+def on_clear_points(frame_idx, video_path):
+    """Clear all selected points."""
+    select_points.clear()
+    if video_path is None:
+        return None, "Points cleared.", format_points()
+    frame = get_frame(video_path, int(frame_idx))
+    return draw_points(frame, select_points), "🗑️ All points cleared.", format_points()
+
+def on_undo_point(frame_idx, video_path):
+    """Remove last selected point."""
+    if select_points:
+        removed = select_points.pop()
+        msg = f"↩️ Removed point at ({removed[0]}, {removed[1]})"
+    else:
+        msg = "No points to undo."
+    if video_path is None:
+        return None, msg, format_points()
+    frame = get_frame(video_path, int(frame_idx))
+    return draw_points(frame, select_points), msg, format_points()
+
+def format_points():
+    """Format select_points for display in the textbox."""
+    if not select_points:
+        return "No points selected yet."
+    lines = [f"  [{i+1}]  x={p[0]},  y={p[1]}" for i, p in enumerate(select_points)]
+    return "select_points:\n" + "\n".join(lines)
+
+def track(video_path, frame_idx, out_video, target_size=(256, 256)):
+    """Placeholder for tracking function — replace with your actual tracking logic."""
+    if video_path is None:
+        status = f"⚠️ No video loaded. Cannot run the tracker."
+        return status
+    if len(select_points) < 1:
+        status = f"⚠️ No points selected. Please select at least one point to track."
+        return status
+    
+    tracker, device = load_model("echotracker_cvamd_ts.pt")
+
+    cap     = cv2.VideoCapture(video_path)
+    W       = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    H       = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    total   = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+    frames = []
+    paint_frames = []
+    while cap.isOpened():
+        ret, frame = cap.read()
+        if not ret:
+            break
+        paint_frames.append(frame)
+        frame = cv2.resize(frame, target_size)
+        frames.append(Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)))
+    cap.release()
+    paint_frames = np.array(paint_frames)
+    frames = torch.from_numpy(np.array(frames)).unsqueeze(0).unsqueeze(2).float().to(device)  # shape: [B, T, H, W]
+    q_points = points_to_tensor(select_points, frame_idx, H, W, 256).to(device)  # shape: [1, N, 3]
+    #print(f"✅ Loaded video frames: {frames.shape} {paint_frames.shape}")
+    # print(f"Selected points: {q_points.shape}")
+    
+    with torch.no_grad():
+        output = tracker(frames, q_points)
+        trajs_e = output[-1].cpu().permute(0, 2, 1, 3)
+    
+    q_points[...,1] /= 256 - 1
+    q_points[...,2] /= 256 - 1
+    trajs_e[...,0] /= 256 - 1
+    trajs_e[...,1] /= 256 - 1
+    #print(f"Tracker output trajectories: {trajs_e.shape}")
+    paint_frames = visualize_tracking(
+        frames=paint_frames, points=trajs_e.squeeze().cpu().numpy(), 
+        vis_color='random',
+        thickness=5,
+        track_length=30,
+    )
+    # Save or display paint_frames as needed (e.g., save as video or show in Gradio)
+    out_vid = "outputs/output.mp4"
+    os.makedirs("outputs", exist_ok=True)
+    media.write_video(out_vid, paint_frames, fps=25)
+    status = f"✅ Tracking completed! The output is visualized below."
+    out_video = gr.update(value=out_vid, autoplay=True, loop=True)
+    return out_video, status
+    
+
+def load_model(model_path: str, device: str = "cuda" if torch.cuda.is_available() else "cpu"):
+    """Load a torchscript model
+
+    Args:
+        model_path (str): path to the torchscript weights
+        device (str, optional): Defaults to "cuda" if torch.cuda.is_available() else "cpu".
+
+    Returns:
+        model: the loaded torchscript model
+    """
+    model = torch.jit.load(model_path, map_location=device).eval()
+    #print(f"✅ TorchScript model loaded on {device}")
+    return model, device
+
+
+# ── Gradio UI ─────────────────────────────────────────────────────────────────
+HEADER = """
+<div style="text-align:center; padding: 20px 0 8px;">
+  <h1 style="font-size:2.2rem; font-weight:700; margin-bottom:4px;">🫀 EchoTracker</h1>
+  <p style="font-size:1.05rem; color:var(--echo-muted); margin:4px 0 0;">
+    Advancing Myocardial Point Tracking in Echocardiography
+  </p>
+  <p style="font-size:0.9rem; color:var(--echo-subtle); margin:2px 0 0;">
+    MICCAI 2024 &nbsp;·&nbsp;
+    Azad, Chernyshov, Nyberg, Tveten, Lovstakken, Dalen, Grenne, Østvik
+  </p>
+  <div style="margin-top:12px; display:flex; justify-content:center; gap:10px; flex-wrap:wrap;">
+    <a href="https://link.springer.com/chapter/10.1007/978-3-031-72083-3_60"
+       target="_blank"
+       style="display:inline-flex;align-items:center;gap:5px;padding:5px 14px;border-radius:6px;
+              background:#2563eb;color:white;font-size:0.85rem;text-decoration:none;font-weight:500;">
+      📄 Paper (MICCAI 2024)
+    </a>
+    <a href="https://arxiv.org/abs/2405.08587" target="_blank"
+       style="display:inline-flex;align-items:center;gap:5px;padding:5px 14px;border-radius:6px;
+              background:#dc2626;color:white;font-size:0.85rem;text-decoration:none;font-weight:500;">
+      📝 ArXiv
+    </a>
+    <a href="https://github.com/riponazad/echotracker" target="_blank"
+       style="display:inline-flex;align-items:center;gap:5px;padding:5px 14px;border-radius:6px;
+              background:#1f2937;color:white;font-size:0.85rem;text-decoration:none;font-weight:500;">
+      💻 GitHub
+    </a>
+    <a href="https://riponazad.github.io/echotracker/" target="_blank"
+       style="display:inline-flex;align-items:center;gap:5px;padding:5px 14px;border-radius:6px;
+              background:#7c3aed;color:white;font-size:0.85rem;text-decoration:none;font-weight:500;">
+      🌐 Project Page
+    </a>
+  </div>
+</div>
+"""
+
+CITATION_MD = """
+If you use EchoTracker in your research, please cite:
+
+```bibtex
+@InProceedings{azad2024echotracker,
+    author    = {Azad, Md Abulkalam and Chernyshov, Artem and Nyberg, John
+                 and Tveten, Ingrid and Lovstakken, Lasse and Dalen, H{\\aa}vard
+                 and Grenne, Bj{\\o}rnar and {\\O}stvik, Andreas},
+    title     = {EchoTracker: Advancing Myocardial Point Tracking in Echocardiography},
+    booktitle = {Medical Image Computing and Computer Assisted Intervention -- MICCAI 2024},
+    year      = {2024},
+    publisher = {Springer Nature Switzerland},
+    doi       = {10.1007/978-3-031-72083-3_60}
+}
+```
+"""
+
+with gr.Blocks(title="EchoTracker", theme=gr.themes.Soft(),
+               css="""
+.gr-button { font-weight: 600; }
+:root  { --echo-muted: #444; --echo-subtle: #666; }
+.dark  { --echo-muted: #c0c0c0; --echo-subtle: #a8a8a8; }
+""",
+               js=_DOWNLOAD_CTRL_JS) as demo:
+
+    gr.HTML(HEADER)
+    gr.Markdown("---")
+
+    # ── Instructions ──────────────────────────────────────────────────────────
+    with gr.Accordion("ℹ️  How to use", open=False):
+        gr.Markdown("""
+1. **Load a video** — upload your own echocardiography clip, or click one of the provided example videos below the panel.
+2. **Navigate** to the desired query frame using the frame slider.
+3. **Click** on the frame image to place tracking points on cardiac tissue surfaces (e.g. LV/RV walls, myocardium).
+4. Use **Undo** or **Clear All** to adjust your selection.
+5. Press **▶ Run EchoTracker** to generate tracked trajectories for all selected points.
+
+> **Tip:** Select points at the *end-diastolic* frame for best results. Up to 100 points are supported.
+> Example clips cover apical 4-chamber (A4C), right-ventricle (RV), and parasternal short-axis (PSAX) views.
+> Clips marked **OOD** (🔶) are out-of-distribution — different scanner or view not seen during training, showcasing EchoTracker's generalisation ability.
+        """)
+
+    # hidden state
+    video_state  = gr.State(value=None)
+    # injects/removes CSS that hides download buttons on example videos
+    download_ctrl = gr.Textbox(value="0", visible=False, elem_id="download_ctrl")
+
+    gr.Markdown("### Step 1 — Upload & Select Query Points")
+    gr.Markdown(
+        "Upload your own echocardiography video, or click one of the **example clips** below to get started."
+    )
+
+    with gr.Row(equal_height=False):
+        # ── Left column: input + points ───────────────────────────────────────
+        with gr.Column(scale=1, min_width=300):
+            video_upload = gr.Video(
+                label="Echocardiography Video — upload yours or use an example below",
+                sources="upload",
+                include_audio=False,
+                autoplay=True,
+                loop=True,
+                elem_id="video_upload_player",
+            )
+            points_display = gr.Textbox(
+                value="No points selected yet.",
+                label="📋 Selected Query Points",
+                lines=5,
+                max_lines=5,
+                interactive=False,
+            )
+            gr.Markdown(
+                "<small style='color:var(--echo-subtle)'>Coordinates are stored as "
+                "<code>np.array([x, y])</code> and passed to the tracker.</small>"
+            )
+
+        # ── Right column: frame viewer + controls ─────────────────────────────
+        with gr.Column(scale=2, min_width=400):
+            frame_display = gr.Image(
+                label="Query Frame — click to place tracking points",
+                interactive=True,
+                type="numpy",
+                sources=[],
+            )
+            frame_slider = gr.Slider(
+                minimum=0, maximum=100, value=0, step=1,
+                label="Frame",
+                interactive=False,
+            )
+            status_text = gr.Textbox(
+                label="Status", lines=1, interactive=False, show_label=False,
+                placeholder="Status messages will appear here…",
+            )
+            with gr.Row():
+                undo_btn  = gr.Button("↩ Undo", scale=1)
+                clear_btn = gr.Button("🗑 Clear All", variant="stop", scale=1)
+
+    gr.Markdown("---")
+    gr.Markdown("### Step 2 — Run Tracker & View Output")
+    with gr.Row():
+        with gr.Column(scale=1):
+            run_btn = gr.Button("▶  Run EchoTracker", variant="primary", size="lg")
+        with gr.Column(scale=2):
+            out_video = gr.Video(
+                label="Tracking Output",
+                sources=[],
+                include_audio=False,
+                interactive=False,
+                autoplay=True,
+                loop=True,
+                elem_id="out_video_player",
+            )
+
+    gr.Markdown("---")
+
+    gr.Markdown(
+        "**Or try an example clip** "
+        "<small style='color:var(--echo-subtle)'>— OOD = out-of-distribution (different scanner / view not seen during training)</small>"
+    )
+    gr.Markdown(
+        "> ⚠️ **Example videos are provided for demonstration purposes only. "
+        "They should not be downloaded, reproduced, or used for any purpose outside this demo.**"
+    )
+    ex_btns = []
+    with gr.Row(equal_height=True):
+        for label, (path, is_ood) in EXAMPLE_VIDEOS.items():
+            with gr.Column(min_width=120):
+                gr.Image(
+                    value=THUMBNAILS[label],
+                    show_label=False,
+                    interactive=False,
+                    height=110,
+                    container=False,
+                )
+                btn_label = f"{label} 🔶" if is_ood else label
+                ex_btns.append(gr.Button(btn_label, size="sm"))
+
+    # ── Citation ──────────────────────────────────────────────────────────────
+    with gr.Accordion("📝  Citation", open=False):
+        gr.Markdown(CITATION_MD)
+
+    # ── Wire events ───────────────────────────────────────────────────────────
+    video_upload.upload(
+        fn=on_video_upload,
+        inputs=[video_upload],
+        outputs=[frame_display, frame_slider, status_text, video_state, download_ctrl]
+    )
+
+    frame_slider.release(
+        fn=on_slider_release,
+        inputs=[frame_slider, video_state, points_display],
+        outputs=[frame_display, status_text, points_display]
+    )
+
+    frame_display.select(
+        fn=on_point_select,
+        inputs=[frame_slider, video_state],
+        outputs=[frame_display, status_text, points_display]
+    )
+
+    undo_btn.click(
+        fn=on_undo_point,
+        inputs=[frame_slider, video_state],
+        outputs=[frame_display, status_text, points_display]
+    )
+
+    clear_btn.click(
+        fn=on_clear_points,
+        inputs=[frame_slider, video_state],
+        outputs=[frame_display, status_text, points_display]
+    )
+
+    for btn, (path, _) in zip(ex_btns, EXAMPLE_VIDEOS.values()):
+        btn.click(
+            fn=load_example,
+            inputs=gr.State(path),
+            outputs=[video_upload, frame_display, frame_slider, status_text, video_state,
+                     out_video, points_display, download_ctrl]
+        )
+
+    run_btn.click(
+        fn=track,
+        inputs=[video_state, frame_slider, out_video],
+        outputs=[out_video, status_text]
+    )
+
+demo.launch(share=False)

echotracker_cvamd_ts.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:596e5357d25cc6fc246bb0f32f0ab12c1dabb521d9577c6207f07a7ccdc03281
+size 40905188

example_samples/input1.mp4

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

example_samples/input2.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:431f6920f0e88de2ed8dec17b52f51c0ceed358885fcb43ef27f2fc462b0b7c7
+size 386306

example_samples/input3_RV.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4ed04601df34c55e8aa98fc8872ec4665557a2ba9a65beda915c7f1ab3139b9a
+size 1364528

example_samples/psax_video_crop.mp4

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

outputs/output.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ad3045a6d841562f52736a6fa49ce57050d2b1682897417511225599152bdb6
+size 630372

requirements.txt

@@ -0,0 +1,7 @@
+torch>=2.0.0
+numpy>=1.24.0
+opencv-python-headless>=4.8.0
+Pillow>=9.5.0
+mediapy>=1.2.0
+scikit-image>=0.21.0
+gradio==6.12.0

utils.py

@@ -0,0 +1,142 @@
+import torch
+import cv2
+import numpy as np
+from skimage.color import gray2rgb
+
+
+def points_to_tensor(points: list, qt: int, orig_H: int, orig_W: int, target: int = 256) -> torch.Tensor:
+    """
+    Convert [(x1,y1), ..., (xn,yn)] to tensor of shape [1, n, 3]
+    where last dim is (qt, x, y), with x/y scaled to target resolution.
+
+    Args:
+        points  : list of (x, y) tuples or np.array([x, y])
+        qt      : single int, same for all points
+        orig_H  : original frame height
+        orig_W  : original frame width
+        target  : target resolution (default 256)
+
+    Returns:
+        tensor of shape [1, n, 3], dtype float32
+    """
+    scale_x = target / orig_W
+    scale_y = target / orig_H
+
+    arr = np.array(
+        [[qt, p[0] * scale_x, p[1] * scale_y] for p in points],
+        dtype=np.float32
+    )  # (n, 3)
+
+    return torch.tensor(arr).unsqueeze(0)  # (1, n, 3)
+
+
+
+def visualize_tracking(
+    frames: np.ndarray, 
+    points: np.ndarray, 
+    tracking_quality: np.ndarray = None,
+    vis_color='random',
+    color_map: np.ndarray = None,
+    gray: bool = False,
+    alpha: float = 1.0,
+    track_length: int = 0,
+    thickness: int = 2,
+) -> np.ndarray:
+
+    num_points, num_frames = points.shape[:2]
+    height, width = frames.shape[1:3]
+
+    if gray and frames.shape[-1] != 3:
+        frames = gray2rgb(frames.squeeze())
+
+    radius = max(6, int(0.006 * min(height, width)))
+
+    quality_colors = {
+        0: np.array([255, 0, 0]),
+        1: np.array([255, 255, 0]),
+        2: np.array([0, 255, 0]),
+    }
+
+    video = frames.copy()
+
+    # Stable random colors
+    if vis_color == 'random' and tracking_quality is None and color_map is None:
+        rand_colors = np.random.randint(0, 256, size=(num_points, 3))
+
+    for t in range(num_frames):
+        overlay = np.zeros_like(video[t], dtype=np.uint8)
+        t_start = max(1, t - track_length)
+
+        for i in range(num_points):
+
+            # -------------------------------------------------
+            # Resolve color ONCE (fixes UnboundLocalError)
+            # -------------------------------------------------
+            if tracking_quality is not None:
+                color = quality_colors.get(
+                    int(tracking_quality[i, t]),
+                    np.array([255, 255, 255])
+                )
+
+            elif color_map is not None:
+                color = np.asarray(color_map[i])
+
+            elif isinstance(vis_color, (list, tuple, np.ndarray)):
+                color = np.asarray(vis_color)
+
+            else:
+                if vis_color == 'random':
+                    color = rand_colors[i]
+                elif vis_color == 'red':
+                    color = quality_colors[0]
+                elif vis_color == 'yellow':
+                    color = quality_colors[1]
+                elif vis_color == 'green':
+                    color = quality_colors[2]
+                else:
+                    raise ValueError(f"Unknown vis_color: {vis_color}")
+
+            color = color.astype(np.uint8)
+
+            # -------------------------------------------------
+            # Draw track lines
+            # -------------------------------------------------
+            for tt in range(t_start, t):
+                fade = (tt - t_start + 1) / max(1, (t - t_start))
+
+                x0n, y0n = points[i, tt - 1]
+                x1n, y1n = points[i, tt]
+
+                x0 = int(np.clip(x0n * width, 0, width - 1))
+                y0 = int(np.clip(y0n * height, 0, height - 1))
+                x1 = int(np.clip(x1n * width, 0, width - 1))
+                y1 = int(np.clip(y1n * height, 0, height - 1))
+
+                faded_color = (color * fade).astype(np.uint8)
+
+                cv2.line(
+                    overlay,
+                    (x0, y0),
+                    (x1, y1),
+                    faded_color.tolist(),
+                    thickness=thickness,
+                    lineType=cv2.LINE_AA
+                )
+
+            # -------------------------------------------------
+            # Draw dot (current position)
+            # -------------------------------------------------
+            xc = int(points[i, t, 0] * width)
+            yc = int(points[i, t, 1] * height)
+
+            cv2.circle(
+                overlay,
+                (xc, yc),
+                radius=radius,
+                color=color.tolist(),
+                thickness=-1
+            )
+
+        video[t] = cv2.addWeighted(video[t], 1.0, overlay, alpha, 0)
+
+    return video