Add example images, procedure details, status indicators, usage tracking

- Add 3 synthetic example face images with gr.Examples on all tabs
- Add dynamic procedure description that updates on selection
- Add animated Processing/Done/Error status indicators with CSS
- Add UsageTracker class for simple JSON-based analytics
- Add processing time to info output
- Improve footer with version, tech stack, and citation link
- Bump version to v0.2.2

README.md

@@ -52,4 +52,4 @@ GPU modes (ControlNet, img2img) with photorealistic rendering are available in t
 - [Wiki](https://github.com/dreamlessx/LandmarkDiff-public/wiki)
 - [Discussions](https://github.com/dreamlessx/LandmarkDiff-public/discussions)
 
-**Version:** v0.2.1
+**Version:** v0.2.2

app.py

@@ -2,8 +2,14 @@
 
 from __future__ import annotations
 
+import json
 import logging
+import os
+import threading
+import time
 import traceback
+from datetime import datetime, timezone
+from pathlib import Path
 
 import cv2
 import gradio as gr
@@ -17,7 +23,7 @@ from landmarkdiff.masking import generate_surgical_mask
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
-VERSION = "v0.2.1"
+VERSION = "v0.2.2"
 
 GITHUB_URL = "https://github.com/dreamlessx/LandmarkDiff-public"
 DOCS_URL = f"{GITHUB_URL}/tree/main/docs"
@@ -33,6 +39,120 @@ PROCEDURE_DESCRIPTIONS = {
     "mentoplasty": "Chin surgery -- adjusts chin projection and vertical height",
 }
 
+# -- Detailed procedure info shown when user selects a procedure --
+PROCEDURE_DETAILS = {
+    "rhinoplasty": (
+        "**Rhinoplasty** (nose reshaping)\n\n"
+        "Modifies the nasal bridge height, tip projection, tip rotation, and alar (nostril) "
+        "width. The landmark displacement targets the nose dorsum, tip, columella, and alar "
+        "base regions. At low intensity (10-30%) the effect is subtle refinement; at high "
+        "intensity (70-100%) the reshaping is more dramatic.\n\n"
+        "Affected landmarks: nasal bridge, tip, alar base, columella"
+    ),
+    "blepharoplasty": (
+        "**Blepharoplasty** (eyelid surgery)\n\n"
+        "Adjusts upper and lower eyelid position and canthal tilt. Targets the periorbital "
+        "region including upper lid crease, lower lid margin, and lateral/medial canthi. "
+        "Simulates both upper blepharoplasty (lid ptosis correction) and lower blepharoplasty "
+        "(under-eye bag removal).\n\n"
+        "Affected landmarks: upper/lower eyelid margins, canthi, periorbital region"
+    ),
+    "rhytidectomy": (
+        "**Rhytidectomy** (facelift)\n\n"
+        "Tightens the midface and jawline by displacing landmarks along vectors that simulate "
+        "SMAS lift and skin redraping. Affects the cheek, jowl, and submental regions. The "
+        "effect tightens nasolabial folds and redefines the jawline contour.\n\n"
+        "Affected landmarks: cheek, jowl, jawline, submental region"
+    ),
+    "orthognathic": (
+        "**Orthognathic surgery** (jaw repositioning)\n\n"
+        "Simulates maxillary and mandibular osteotomy outcomes by repositioning the skeletal "
+        "framework. Affects jaw position, chin projection, and overall facial proportion. "
+        "Used for correcting class II/III malocclusion and facial asymmetry.\n\n"
+        "Affected landmarks: maxilla, mandible, chin, lower face contour"
+    ),
+    "brow_lift": (
+        "**Brow lift** (forehead rejuvenation)\n\n"
+        "Elevates brow position and reduces forehead ptosis. Targets the eyebrow arch, "
+        "lateral brow tail, and glabellar region. Simulates both endoscopic and coronal "
+        "brow lift approaches. Higher intensities produce more visible brow elevation.\n\n"
+        "Affected landmarks: brow arch, lateral brow, glabella, upper forehead"
+    ),
+    "mentoplasty": (
+        "**Mentoplasty** (chin surgery)\n\n"
+        "Adjusts chin projection (anteroposterior position) and vertical height. Simulates "
+        "both augmentation (advancement) and reduction genioplasty. Affects the pogonion, "
+        "menton, and lower border of the mandible.\n\n"
+        "Affected landmarks: chin point, lower mandibular border, mentolabial fold"
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Usage analytics -- simple thread-safe counter persisted to disk
+# ---------------------------------------------------------------------------
+class UsageTracker:
+    """Track demo usage counts to a JSON file (thread-safe)."""
+
+    def __init__(self, path: str = "usage_stats.json"):
+        self._path = Path(path)
+        self._lock = threading.Lock()
+        self._stats: dict = self._load()
+
+    def _load(self) -> dict:
+        if self._path.exists():
+            try:
+                return json.loads(self._path.read_text())
+            except (json.JSONDecodeError, OSError):
+                pass
+        return {
+            "total_runs": 0,
+            "procedures": {},
+            "tabs": {},
+            "first_run": None,
+            "last_run": None,
+        }
+
+    def _save(self) -> None:
+        try:
+            self._path.write_text(json.dumps(self._stats, indent=2))
+        except OSError:
+            logger.warning("Could not persist usage stats")
+
+    def record(self, tab: str, procedure: str | None = None) -> None:
+        with self._lock:
+            now = datetime.now(timezone.utc).isoformat()
+            self._stats["total_runs"] = self._stats.get("total_runs", 0) + 1
+            if self._stats.get("first_run") is None:
+                self._stats["first_run"] = now
+            self._stats["last_run"] = now
+
+            tabs = self._stats.setdefault("tabs", {})
+            tabs[tab] = tabs.get(tab, 0) + 1
+
+            if procedure:
+                procs = self._stats.setdefault("procedures", {})
+                procs[procedure] = procs.get(procedure, 0) + 1
+
+            self._save()
+
+    @property
+    def total_runs(self) -> int:
+        return self._stats.get("total_runs", 0)
+
+    @property
+    def summary(self) -> str:
+        total = self._stats.get("total_runs", 0)
+        top_proc = ""
+        procs = self._stats.get("procedures", {})
+        if procs:
+            top = max(procs, key=procs.get)
+            top_proc = f" | Most popular: {top.replace('_', ' ').title()}"
+        return f"Total runs: {total}{top_proc}"
+
+
+tracker = UsageTracker()
+
 
 def warp_image_tps(image, src_pts, dst_pts):
     """Thin-plate spline warp (CPU only)."""
@@ -56,11 +176,20 @@ def _error_result(msg):
     return blank, blank, blank, blank, msg
 
 
+def _get_procedure_description(procedure: str) -> str:
+    """Return the detailed Markdown description for a procedure."""
+    return PROCEDURE_DETAILS.get(procedure, "Select a procedure to see details.")
+
+
 def process_image(image_rgb, procedure, intensity):
     """Process a single image through the TPS pipeline."""
+    tracker.record("single", procedure)
+
     if image_rgb is None:
         return _error_result("Upload a face photo to begin.")
 
+    t0 = time.monotonic()
+
     try:
         image_bgr = cv2.cvtColor(np.asarray(image_rgb, dtype=np.uint8), cv2.COLOR_RGB2BGR)
         image_bgr = cv2.resize(image_bgr, (512, 512))
@@ -103,12 +232,15 @@ def process_image(image_rgb, procedure, intensity):
             np.linalg.norm(manipulated.pixel_coords - face.pixel_coords, axis=1)
         )
 
+        elapsed = time.monotonic() - t0
+
         info = (
             f"Procedure: {procedure}\n"
             f"Intensity: {intensity:.0f}%\n"
             f"Landmarks: {len(face.landmarks)}\n"
             f"Avg displacement: {displacement:.1f} px\n"
             f"Confidence: {face.confidence:.2f}\n"
+            f"Processing time: {elapsed:.2f}s\n"
             f"Mode: TPS (CPU)"
         )
         return wireframe_rgb, mask_vis, composited_rgb, side_by_side, info
@@ -120,6 +252,8 @@ def process_image(image_rgb, procedure, intensity):
 
 def compare_procedures(image_rgb, intensity):
     """Compare all procedures at the same intensity."""
+    tracker.record("compare")
+
     if image_rgb is None:
         blank = np.zeros((512, 512, 3), dtype=np.uint8)
         return [blank] * len(PROCEDURES)
@@ -150,6 +284,8 @@ def compare_procedures(image_rgb, intensity):
 
 def intensity_sweep(image_rgb, procedure):
     """Generate intensity sweep from 0 to 100."""
+    tracker.record("sweep", procedure)
+
     if image_rgb is None:
         return []
 
@@ -179,6 +315,10 @@ def intensity_sweep(image_rgb, procedure):
         return []
 
 
+# -- Example images --
+EXAMPLE_DIR = Path(__file__).parent / "examples"
+EXAMPLE_IMAGES = sorted(EXAMPLE_DIR.glob("*.png")) if EXAMPLE_DIR.exists() else []
+
 # -- Build the procedure table for the description --
 _proc_rows = "\n".join(
     f"| **{name.replace('_', ' ').title()}** | {desc} |"
@@ -228,22 +368,74 @@ pipeline for photorealistic rendering, followed by CodeFormer + Real-ESRGAN post
 
 FOOTER_MD = f"""
 ---
-<p style="text-align:center; color:#888; font-size:0.85em;">
-LandmarkDiff {VERSION} &middot;
-<a href="{GITHUB_URL}">GitHub</a> &middot;
-<a href="{WIKI_URL}">Wiki</a> &middot;
-<a href="{DISCUSSIONS_URL}">Discussions</a> &middot;
-MIT License
-</p>
+<div style="text-align:center; color:#888; font-size:0.85em; padding: 12px 0;">
+  <p>
+    <strong>LandmarkDiff</strong> {VERSION} &middot;
+    TPS warping on CPU &middot;
+    MediaPipe 478-point mesh &middot;
+    6 surgical procedures
+  </p>
+  <p>
+    <a href="{GITHUB_URL}">GitHub</a> &middot;
+    <a href="{DOCS_URL}">Docs</a> &middot;
+    <a href="{WIKI_URL}">Wiki</a> &middot;
+    <a href="{DISCUSSIONS_URL}">Discussions</a> &middot;
+    MIT License
+  </p>
+  <p style="font-size:0.75em; color:#aaa;">
+    Built with Gradio &middot;
+    Powered by MediaPipe + OpenCV &middot;
+    <a href="{GITHUB_URL}/blob/main/CITATION.cff">Cite this work</a>
+  </p>
+</div>
 """
 
 
 with gr.Blocks(
     title="LandmarkDiff - Surgical Outcome Prediction",
     theme=gr.themes.Soft(),
+    css="""
+    .status-processing {
+        background: linear-gradient(90deg, #e3f2fd 0%, #bbdefb 50%, #e3f2fd 100%);
+        background-size: 200% 100%;
+        animation: shimmer 2s infinite;
+        padding: 8px 16px;
+        border-radius: 6px;
+        text-align: center;
+        font-weight: 500;
+    }
+    @keyframes shimmer {
+        0% { background-position: -200% 0; }
+        100% { background-position: 200% 0; }
+    }
+    .status-ready {
+        background: #e8f5e9;
+        padding: 8px 16px;
+        border-radius: 6px;
+        text-align: center;
+        color: #2e7d32;
+        font-weight: 500;
+    }
+    .status-error {
+        background: #ffebee;
+        padding: 8px 16px;
+        border-radius: 6px;
+        text-align: center;
+        color: #c62828;
+        font-weight: 500;
+    }
+    .proc-detail-box {
+        background: #f5f5f5;
+        border-left: 3px solid #1976d2;
+        padding: 12px 16px;
+        border-radius: 4px;
+        margin-top: 8px;
+    }
+    """,
 ) as demo:
     gr.Markdown(HEADER_MD)
 
+    # -- Single Procedure tab --
     with gr.Tab("Single Procedure"):
         with gr.Row():
             with gr.Column(scale=1):
@@ -253,6 +445,10 @@ with gr.Blocks(
                     value="rhinoplasty",
                     label="Surgical Procedure",
                 )
+                proc_detail = gr.Markdown(
+                    value=_get_procedure_description("rhinoplasty"),
+                    elem_classes=["proc-detail-box"],
+                )
                 intensity = gr.Slider(
                     minimum=0,
                     maximum=100,
@@ -262,7 +458,11 @@ with gr.Blocks(
                     info="0 = no change, 100 = maximum effect",
                 )
                 run_btn = gr.Button("Generate Preview", variant="primary", size="lg")
-                info_box = gr.Textbox(label="Info", lines=6, interactive=False)
+                status_box = gr.HTML(
+                    value='<div class="status-ready">Ready -- upload a photo or click an example below</div>',
+                    label="Status",
+                )
+                info_box = gr.Textbox(label="Info", lines=7, interactive=False)
 
             with gr.Column(scale=2):
                 with gr.Row():
@@ -272,18 +472,59 @@ with gr.Blocks(
                     out_result = gr.Image(label="Predicted Result", height=256)
                     out_sidebyside = gr.Image(label="Before / After", height=256)
 
+        # -- Example images --
+        if EXAMPLE_IMAGES:
+            gr.Markdown("### Try an Example")
+            gr.Examples(
+                examples=[[str(p)] for p in EXAMPLE_IMAGES],
+                inputs=[input_image],
+                label="Click an example face to load it (these are synthetic sketches "
+                      "-- for best results, upload a real photo)",
+            )
+
+        # -- Procedure description update --
+        procedure.change(
+            fn=_get_procedure_description,
+            inputs=[procedure],
+            outputs=[proc_detail],
+        )
+
+        # -- Processing with status indicator --
+        def _process_with_status(image_rgb, proc, intens):
+            results = process_image(image_rgb, proc, intens)
+            # Last element is the info/error text
+            info_text = results[-1]
+            if "error" in info_text.lower() or "No face" in info_text:
+                status_html = f'<div class="status-error">{info_text.split(chr(10))[0]}</div>'
+            else:
+                status_html = '<div class="status-ready">Done -- result ready</div>'
+            return results + (status_html,)
+
+        all_outputs = [out_wireframe, out_mask, out_result, out_sidebyside, info_box, status_box]
+
         run_btn.click(
-            fn=process_image,
+            fn=lambda: '<div class="status-processing">Processing... extracting landmarks and warping</div>',
+            inputs=None,
+            outputs=[status_box],
+        ).then(
+            fn=_process_with_status,
             inputs=[input_image, procedure, intensity],
-            outputs=[out_wireframe, out_mask, out_result, out_sidebyside, info_box],
+            outputs=all_outputs,
         )
+
+        # Auto-trigger on input change (image upload, procedure change, intensity change)
         for trigger in [input_image, procedure, intensity]:
             trigger.change(
-                fn=process_image,
+                fn=lambda: '<div class="status-processing">Processing...</div>',
+                inputs=None,
+                outputs=[status_box],
+            ).then(
+                fn=_process_with_status,
                 inputs=[input_image, procedure, intensity],
-                outputs=[out_wireframe, out_mask, out_result, out_sidebyside, info_box],
+                outputs=all_outputs,
             )
 
+    # -- Compare Procedures tab --
     with gr.Tab("Compare Procedures"):
         gr.Markdown("Compare all six procedures side by side at the same intensity.")
         with gr.Row():
@@ -291,6 +532,9 @@ with gr.Blocks(
                 cmp_image = gr.Image(label="Upload Face Photo", type="numpy", height=300)
                 cmp_intensity = gr.Slider(0, 100, 50, step=1, label="Intensity (%)")
                 cmp_btn = gr.Button("Compare All", variant="primary", size="lg")
+                cmp_status = gr.HTML(
+                    value='<div class="status-ready">Ready</div>',
+                )
             with gr.Column(scale=2):
                 cmp_outputs = []
                 rows_needed = (len(PROCEDURES) + 2) // 3
@@ -306,12 +550,29 @@ with gr.Blocks(
                                     )
                                 )
 
+        # Example images for Compare tab
+        if EXAMPLE_IMAGES:
+            gr.Examples(
+                examples=[[str(p)] for p in EXAMPLE_IMAGES],
+                inputs=[cmp_image],
+                label="Example faces",
+            )
+
+        def _compare_with_status(img, intens):
+            results = compare_procedures(img, intens)
+            return results + ['<div class="status-ready">Done -- 6 procedures compared</div>']
+
         cmp_btn.click(
-            fn=compare_procedures,
+            fn=lambda: '<div class="status-processing">Processing 6 procedures...</div>',
+            inputs=None,
+            outputs=[cmp_status],
+        ).then(
+            fn=_compare_with_status,
             inputs=[cmp_image, cmp_intensity],
-            outputs=cmp_outputs,
+            outputs=cmp_outputs + [cmp_status],
         )
 
+    # -- Intensity Sweep tab --
     with gr.Tab("Intensity Sweep"):
         gr.Markdown(
             "See how a procedure looks across intensity levels (0% through 100% in 20% steps)."
@@ -325,15 +586,38 @@ with gr.Blocks(
                     label="Procedure",
                 )
                 sweep_btn = gr.Button("Generate Sweep", variant="primary", size="lg")
+                sweep_status = gr.HTML(
+                    value='<div class="status-ready">Ready</div>',
+                )
             with gr.Column(scale=2):
                 sweep_gallery = gr.Gallery(
                     label="Intensity Sweep (0% - 100%)", columns=3, height=400
                 )
 
+        # Example images for Sweep tab
+        if EXAMPLE_IMAGES:
+            gr.Examples(
+                examples=[[str(p)] for p in EXAMPLE_IMAGES],
+                inputs=[sweep_image],
+                label="Example faces",
+            )
+
+        def _sweep_with_status(img, proc):
+            results = intensity_sweep(img, proc)
+            if results:
+                status = '<div class="status-ready">Done -- 6 intensity levels generated</div>'
+            else:
+                status = '<div class="status-error">No face detected or processing failed</div>'
+            return results, status
+
         sweep_btn.click(
-            fn=intensity_sweep,
+            fn=lambda: '<div class="status-processing">Generating 6 intensity levels...</div>',
+            inputs=None,
+            outputs=[sweep_status],
+        ).then(
+            fn=_sweep_with_status,
             inputs=[sweep_image, sweep_procedure],
-            outputs=[sweep_gallery],
+            outputs=[sweep_gallery, sweep_status],
         )
 
     gr.Markdown(FOOTER_MD)